Authorization

PrivMX Bridge supports several authorization methods: API Keys, Signatures, and Access Tokens This section explains how to use them securely and effectively.

API Keys

You can access the API using API Keys.

API Keys have no time-to-live (TTL), but they can be disabled or deleted.
Each key has a specific scope.
You can create up to 10 API Keys with the method manager/createApiKey.

When you install PrivMX Bridge, you receive your first API Key with full API access.

Creating an API Key

Without Public Key

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: one-of-our-authorization-methods" \
  --data-binary '{
      "jsonrpc": "2.0",
      "id": 0,
      "method": "manager/createApiKey",
      "params": {
          "name": "My ApiKey",
          "scope": ["apikey", "context", "solution"]
      }
  }' \
  https://my-privmx-bridge-instance/api

With Public Key (ED25519 PEM)

curl -X POST -H "Content-Type: application/json" \
    -H "Authorization: one-of-our-authorization-methods" \
    --data-binary '{
        "jsonrpc": "2.0",
        "id": 0,
        "method": "manager/createApiKey",
        "params": {
            "name": "My ApiKey",
            "scope": ["apikey", "context", "solution"],
            "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEADsSTjY2wnm1iwWamIWwLTPVhtTIb8TVlI8tts3wkhkQ=\n-----END PUBLIC KEY-----"
        }
    }' \
    https://my-privmx-bridge-instance/api

API Key Response

{
    "jsonrpc":"2.0",
    "id":0,
    "result": {
        "id": "hysd62jsd7823nasd03",
        "secret": "759a1d8edba555badf1216b0f381b94950141"
    }
}

Signatures

You can sign your request using your API Key.

1. Prepare Data to Sign

apiKeyId = "6XMc4VMf3q54YNarSn9CWUn4htStNu1ry9ajamemdo23sS1y21";
requestPayload = '{"jsonrpc":"2.0","id":0,"method":"solution/listSolutions","params":{}}';
requestData = `POST\n/api\n${requestPayload}\n`; 
timestamp = 1702555410352;
nonce = "3xUee4EA0gr8dg==";
dataToSign = `${timestamp};${nonce};${requestData}`;

`requestData` format

The requestData string is always constructed in the following format:

UPPERCASE(HTTP_METHOD()) + "\n" + URI() + "\n" + RequestBody + "\n";

HTTP_METHOD() → the HTTP method in uppercase (e.g. POST, GET)
URI() → the request path (e.g. /api)
RequestBody → the raw JSON payload of the request
Each part is separated by a newline character (\n), and the string ends with a newline.

2. Generate Signature

HMAC signature:
apiKeySecret = "CspXxVtTyE3sf6jB7z4CSjxoymuS2H67ZjNDfovTu3i8"; signature = BASE64(HMACSHA256(apiKeySecret, dataToSign).SUBARRAY(0, 20))
ECC signature (if publicKey was provided):
privateKey = "-----BEGIN PRIVATE KEY-----\nMC4CAQAwBQYDK2VwBCIEIOBVFGaSFtfqbNvZWctFKg3k+I0T5YXRavpKAD9+BgCX\n-----END PRIVATE KEY-----"; signature = BASE64(SIGN(dataToSign, privateKey))

3. Add Authorization Header

`pmx-hmac-sha256 ${apiKeyId};1;${timestamp};${nonce};${signature}`

curl -X POST -H "Content-Type: application/json" \
     -H "Authorization: pmx-hmac-sha256 6XMc4VMf3q54YNarSn9CWUn4htStNu1ry9ajamemdo23sS1y21;1;1702555410352;3xUee4EA0gr8dg;JN5llLladWZ+1rGu6yrkbIQzme0=" \
     --data-binary '{
         "jsonrpc": "2.0",
         "id": 0,
         "method": "solution/listSolutions",
         "params": {}
     }' \
     https://my-privmx-bridge-instance/api

API Key Credentials

You can also authorize requests by including your API Key credentials directly in the Authorization header:

basicAuthorization = BASE64(`${apiKeyId}:${apiKeySecret}`);
authorizationHeaderValue = `Basic ${basicAuthorization}`;

curl -X POST -H "Content-Type: application/json" \
    -H "Authorization: Basic YWxpY2U6dGhlc2NlcmV0" \
    --data-binary '{
        "jsonrpc": "2.0",
        "id": 0,
        "method": "solution/listSolutions",
        "params": {}
    }' \
    https://my-privmx-bridge-instance/api

Access Tokens

Access Tokens have a TTL but can be refreshed with Refresh Tokens. They are generated using the manager/auth method.

Request Example

curl -X POST \
    -H "Content-Type: application/json" \
    --data-binary '{
        "jsonrpc": "2.0",
        "id": 128,
        "method": "manager/auth",
        "params": {
            "scope": ["apikey", "solution"],
            "grantType": "api_key_credentials",
            "apiKeyId": "65ad8f6b2e4f4f1adb40bf68",
            "apiKeySecret": "5ZTUQ7VBxoqRKn3pEyPjHeavXHVw7JcJF3MvAV43yfsR"
        }
    }' \
    https://my-privmx-bridge-instance/api

Response Example

{
    "jsonrpc": "2.0",
    "id": 128,
    "result": {
        "accessToken": "Base64EncodedToken...",
        "accessTokenExpiry": 1726652150623,
        "refreshToken": "Base64EncodedRefresh...",
        "refreshTokenExpiry": 1726952150623,
        "tokenType": "Bearer",
        "scope": ["apiKey", "solution", "context"]
    }
}

Using Access Token

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Base64EncodedToken..." \
    --data-binary '{
        "jsonrpc": "2.0",
        "id": 128,
        "method": "solution/listSolutions",
        "params": {}
    }' \
    https://my-privmx-bridge-instance/api

Refreshing Token

curl -X POST \
    -H "Content-Type: application/json" \
    --data-binary '{
        "jsonrpc": "2.0",
        "id": 128,
        "method": "manager/auth",
        "params": {
            "grantType": "refresh_token",
            "refreshToken": "Base64EncodedRefresh..."
        }
    }' \
    https://my-privmx-bridge-instance/api

API Scopes

When requesting an Access Token, you can specify the scope, which defines the level of granted access.

Scope	Description
`session:NAME`	Creates a new session with the given name. Each user can have up to 16 sessions; the oldest is removed once the limit is reached.
`ipAddr:ADDR`	Restricts the token to connections from a specific IPv4 address.
`expiresIn:NUMBER`	Sets custom expiry for the token in milliseconds (cannot exceed the refresh token’s TTL).
`solution`	Grants access to Solution API scope.
`context`	Grants access to Context API scope.
`thread`	Grants access to Thread API scope.
`store`	Grants access to Store API scope.
`inbox`	Grants access to Inbox API scope.
`stream`	Grants access to Stream API scope.
`solution:SOLUTION_ID`	Grants access only to Contexts under the given Solution ID.
`solution:*`	Grants access to manage all Contexts.

Scopes enable fine-grained control over permissions and help secure different parts of the system.

On this page