Privacy Portal

API Documentation

Welcome to the Privacy Portal API documentation.
API Endpoint:https://api.privacyportal.org/

Authentication

Authentication depends on the request type:
  • Public: do not require any authentication
  • Implicit Authentication: authentication is included in the request parameters or request body (e.g. OAUTH2 requests)
  • Bearer Access Token: authentication header with Bearer token set to the OAUTH2 Access Token
  • API Key Authentication: authentication headers using API Key

API Key Authentication

  1. Generate your API Key from the security page of the Privacy Portal app.
    {
      "key": "<KEY_ID>",
      "secret": "<KEY_SECRET>"
    }
  2. Record the current Timestamp
    TIMESTAMP = GET_CURRENT_TIMESTAMP()
  3. Sign your request information and timestamp using the following formula
    SIGNATURE = BASE64URL(
      HMAC_SHA256(
        "timestamp\n" +
        "method\n" +
        "url\n" +
        "body"?,
        "<KEY_SECRET>"
      )
    )
  4. Add the timestamp header "X-PP-TS" and the authorization header "authorization" to the request:
    {
      "headers": {
        "authorization": "PP <KEY_ID>:<SIGNATURE>",
        "X-PP-TS": "<TIMESTAMP>"
      }
    }

Mail Relay

Mail Relay api for managing privacy aliases

New Alias Suggestion

Returns a new Privacy Alias suggestion that would need to be created using a POST request before use. This step is not required unless you want to have the ability to modify the suggestion before creating the alias.

Authorization:

API Key Authentication

Responses

Response samples

200
application/json
{
  "address": "[email protected]"
}

Create New Alias

Creates a new Privacy Alias that forwards mail to the main mailbox.

Authorization:

API Key Authentication
REQUEST BODY SCHEMA:
application/json
required

label required
address
note
unique

Responses

Request samples

Payload
application/json
{
  "label": "https://website.example",
  "address": "[email protected]",
  "note": "Alias used to create a website.example account",
  "unique": false
}

Response samples

201
application/json
{
  "id": "32d3cf3c-0078-4ef4-867b-d3f8819913e0",
  "label": "https://privacy-newsletter.example",
  "value": "[email protected]",
  "note": "The Privacy Alias created.",
  "fwd_to": "66aa0d9b-8846-4db3-9b02-5bb9c16e04e3",
  "created_at": 1715957381841,
  "updated_at": 1715957381841
}

Privacy Portal Account

APIs for managing your Privacy Portal Account

API key Info

Returns the information of the current authentication key

Authorization:

API Key Authentication

PATH PARAMS


key_id required

Responses

Response samples

200
application/json
{
  "label": "Awesome App",
  "key": "<KEY_ID>",
  "created_at": 1715974583353,
  "expires_at": 1723750583353
}

Delete API key

Deletes an API Key

Authorization:

API Key Authentication

PATH PARAMS


key_id required

Responses

Response samples

200
application/json
{
  "success": true
}

OAUTH2 - Back Channel

Sign In with Privacy Portal - back channel APIs used by Relying Parties

Issue Access Token

OAUTH2 back-channel request called from Relying Parties to issue Access Tokens

Authorization:

Implicit Authentication
QUERY PARAMS:
application/x-www-form-urlencoded

client_id required
client_secret required
grant_type required
code
refresh_token
redirect_uri
scope
code_verifier
REQUEST BODY SCHEMA:
application/json

client_id required
client_secret required
grant_type required
code
refresh_token
redirect_uri
scope

Responses

Request samples

Payload
application/x-www-form-urlencoded
{
  "client_id": "0388dc0d-5b11-4e0f-ae38-faed564fa9fe",
  "client_secret": "7e467f24-d2d8-4f9e-afe0-18d79de48818",
  "grant_type": "authorization_code",
  "code": "92ec0c29-e4f7-4959-9509-94e455992eab",
  "redirect_uri": "https://awesome-app.example/oauth/callback"
}
Payload
application/json
{
  "client_id": "0388dc0d-5b11-4e0f-ae38-faed564fa9fe",
  "client_secret": "7e467f24-d2d8-4f9e-afe0-18d79de48818",
  "grant_type": "authorization_code",
  "code": "92ec0c29-e4f7-4959-9509-94e455992eab",
  "redirect_uri": "https://awesome-app.example/oauth/callback"
}

Response samples

200
application/json
{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "Bearer",
  "id_token": "<JWT_ID_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "expires": 86400
}
400
application/json
{
  "error": "invalid_client",
  "error_description": "App not found."
}

Revoke Refresh Token

OAUTH2 back-channel request called from Relying Parties to revoke refresh tokens

Authorization:

Implicit Authentication
REQUEST BODY SCHEMA:
application/json
required

client_id required
client_secret required
refresh_token required

Responses

Request samples

Payload
application/json
{
  "client_id": "0388dc0d-5b11-4e0f-ae38-faed564fa9fe",
  "client_secret": "7e467f24-d2d8-4f9e-afe0-18d79de48818",
  "refresh_token": "<REFRESH_TOKEN>"
}

Response samples

200
application/json
{
  "success": true
}
400
application/json
{
  "error": "invalid_request",
  "error_description": "Invalid Refresh Token."
}

OAUTH2 - Resource Services

Resource Services - authenticated with Access Tokens as authorization headers of type "Bearer"

Get User Info

Request to get OpenID user info.

Authorization:

Bearer Access Token

Responses

Response samples

200
application/json
{
  "sub": "54b0a404-9d83-4c8a-a9af-0628fc281340",
  "name": "Max Power",
  "email": "[email protected]"
}

Create API Key

Creates a new API Key. Requires OAUTH2 scope "w:api_keys"

Authorization:

Bearer Access Token
REQUEST BODY SCHEMA:
application/json
required

label required

Responses

Response samples

201
application/json
{
  "label": "Awesome App",
  "key": "<KEY_ID>",
  "secret": "<KEY_SECRET>",
  "expires_at": 1723750583353,
  "created_at": 1715974583353
}

OAUTH2 - OpenID

Sign In with Privacy Portal - OpenID APIs

Get JSON Web Keys

OpenID JWK endpoint used to validate ID Tokens

Authorization:

Public

Responses

Response samples

200
application/json
{
  "keys": [
    {
      "key_ops": [
        "verify"
      ],
      "ext": true,
      "kty": "RSA",
      "n": "zsrMUox6rNAFhggI0SVSYGARhUdIV-DwRCZosCihaGLK7yeJ-14R3Bjk5GsWRRDdTowJKGd5JOK9NNnQcI83xuHWPbN2JZmCmS3X6HGUFKZPF-CQYIMUd4eNOG0vxu2HT2FccTQUDvBdJyjjtL0aM9WSBXaF772DW67TKwLc_PMS_V4O_Zsp2RXCe30Yng9yRCAgsK40dRRoQrs8YHYg10CPl1n-UJXrF_oT-V2Rpz9Osw0rkZT4iOgUbo7wffcq_1xPaICTLhQKCZLVDYuYfpWXeidnPg8iVumFTdjGFX_oL1O8m-pSTG1-Yqj3gIS9Ry2eLwj1wiG2R4LplpUKkw",
      "e": "AQAB",
      "alg": "PS256",
      "kid": "vL0j4YuT"
    }
  ]
}

Get OpenId Config

Get OpenID configuration using the ".well-known" standard endpoint

Authorization:

Public

Responses