API

There is publicly available Swagger documentation. It can be found here

To authenticate at the page please follow the instruction provided at Authentication Section

Client-first integration

To implement this approach all we need to do is use API_KEY

Principal scheme if integration is described below

sequenceDiagram
    title Client-first integration
    autonumber
    actor Client as HTTP Client 
    participant ProtectApp as PRIVO Protect App<br/> (protect.privo.com)
    Client->>+ProtectApp: /api/v1.0/lookup/by-plain-value/[ServiceIdentifier]/[JurisdictionIdentifier]
    Note over Client,ProtectApp: Auth header: `x-api-key`: ABC....123
    alt API KEY is invalid
        ProtectApp->>+Client: 403 Forbidden
    else API KEY is valid
        
        opt Attribute found
            ProtectApp->>+Client:  att_type, value, status
            Note over ProtectApp,Client:   status: found
        end
        opt attribute not found
            ProtectApp->>+Client: att_type, value, status
            Note over ProtectApp,Client: status: found
        end
        opt invalid hash provided
            ProtectApp->>+Client: att_type, value, status
            Note over ProtectApp,Client: status: bad_data
        end
    end

Server-to-server integration

In this scenario Partner's Client invokes Partner server which maintains Privo Auth session and performs lookup calls to PRIVO Protect API.

sequenceDiagram
    title Server-to-server integration
    autonumber
    actor PartnerWebClient as Partner Client
    participant PartnerBackend as Partner Backend
    participant ApiGW as PRIVO API Gateway Svc<br/> (https://api-gw-svc.privo.com/)
    participant ProtectApp as PRIVO Protect App<br/> (protect.privo.com)
    PartnerWebClient ->>+PartnerBackend: Lookup request 
    PartnerBackend->>+ApiGW: Token Request
    Note over PartnerBackend,ApiGW: client_id, client_secret
    ApiGW -->>+PartnerBackend : Token Response:
    Note over ApiGW,PartnerBackend: access_token, exp, ...
    PartnerBackend->>+ProtectApp: /api/v1.0/s2s/lookup/by-plain-value/[ServiceIdentifier]/[JurisdictionIdentifier]
    Note over PartnerBackend,ProtectApp: Authorization: Bearer {{access_token}}
    Note over PartnerBackend,ProtectApp: Lookup Request:  {"att_type", "email", "value" : "some_value"}
    alt Auth token invalid/expired
        ProtectApp->>+PartnerBackend: 403 Forbidden
    else Auth token valid
        opt Attribute found
            ProtectApp->>+PartnerBackend:  att_type, value, status
            Note over ProtectApp,PartnerBackend:   status: found
        end
        opt attribute not found
            ProtectApp->>+PartnerBackend: att_type, value, status
            Note over ProtectApp,PartnerBackend: status: found
        end
        opt invalid hash provided
            ProtectApp->>+PartnerBackend: att_type, value, status
            Note over ProtectApp,PartnerBackend: status: bad_data
        end
    end
    PartnerBackend -->>+PartnerWebClient: Lookup response