Privacy Portal

API Documentation

Hello Developers!
Please use Github Issues to suggest any improvements to our API documentation.
Happy coding!

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
string
Example: https://privacy-newsletter.example
label for the Privacy Alias. When signing up to a website using the website URL is recommended for good interoperability with the browser extensions.
address
string
Example: [email protected]
If you have already requested an alias suggestion, you can pass it here. Otherwise a new alias will be created.
note
string
Example: used to sign up to the privacy newsletter
You can add a note to your alias for future use.
unique
boolean
Example: true
If unique is set to true, the server will only create an alias if no other alias exists under the same label. If a match is found, the server will simply return the existing alias.

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
string
Example: 2c41e8c9-34ef-4465-8e0e-85cbbfd82779
Key ID (must match the Key used in the authorization header)

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
string
Example: 2c41e8c9-34ef-4465-8e0e-85cbbfd82779
Key ID (must match the Key used in the authorization header)

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
string
Relying Party client_id created using the Privacy Portal app
client_secret required
string
Relying Party client_secret created using the Privacy Portal app
grant_type required
string
Example: authorization_code
OAUTH2 grant type. Accepted values: "authorization_code" or "refresh_token".
code
string
OAUTH2 authorization code received from authorization callback. This is required if the grant_type is "authorization_code".
refresh_token
string
OAUTH2 refresh_token. This is required if the grant_type is "refresh_token".
redirect_uri
string
The redirect_uri is used with "authorization_code" grant_type. It is required if the OAUTH2 app has more than one callback URLs.
scope
string
Example: openid name email
The scope can be used with "refresh_token" grant_type. It allows you to Relying Parties to reduce the scope of requested Access Token when needed. You can get the full list of supported scopes at https://api.privacyportal.org/.well-known/openid-configuration
code_verifier
string
PKCE code verifier is a high-entropy cryptographic random STRING with a minimum length of 43 characters and a maximum length of 128 characters. Allowed characters: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~".
REQUEST BODY SCHEMA:
application/json
client_id required
string
Relying Party client_id created using the Privacy Portal app
client_secret required
string
Relying Party client_secret created using the Privacy Portal app
grant_type required
string
Example: authorization_code
OAUTH2 grant type. Accepted values: "authorization_code" or "refresh_token".
code
string
OAUTH2 authorization code received from authorization callback. This is required if the grant_type is "authorization_code".
refresh_token
string
OAUTH2 refresh_token. This is required if the grant_type is "refresh_token".
redirect_uri
string
The redirect_uri is used with "authorization_code" grant_type. It is required if the OAUTH2 app has more than one callback URLs.
scope
string
Example: openid name email
The scope can be used with "refresh_token" grant_type. It allows you to Relying Parties to reduce the scope of requested Access Token when needed. You can get the full list of supported scopes at https://api.privacyportal.org/.well-known/openid-configuration

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
string
Relying Party client_id created using the Privacy Portal app
client_secret required
string
Relying Party client_secret created using the Privacy Portal app
refresh_token required
string
The refresh token to be revoked.

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
string
API Key label

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