Authentication

The Opaque REST API uses three authentication types: refresh tokens, session tokens, and user identity secrets. Each is unique to a user and must be kept secure to prevent unauthorized access.

Overview of authentication types

The following table summarizes our authentication types.

Refresh token

A refresh token is used to generate a new session token without requiring the user to log in again. This enhances security by allowing session renewal while keeping authentication credentials protected. Refresh tokens should be stored securely and used only for obtaining new session tokens.

• Cookie-based refresh: When using browser-based authentication, the refresh token is typically stored as an HttpOnly cookie and sent automatically with requests.

Session token

A session token is a JSON web token (JWT) that securely authenticates API calls. These tokens are valid for 10 minutes. It can be provided in two ways:

• Bearer token: Include the session token in the Authorization request header using the Bearer authentication scheme (default method).
• Cookie: For browser-based requests (e.g., file downloads), include the session token in a cookie parameter.

Endpoint to fetch session tokens:

• /auth/refresh-token (exchanges a valid refresh token for a new session token)

User identity secret

A user identity secret is an API key used for cryptographic operations and sensitive data APIs, such as:

• Uploading data
• Retrieving job results

Include the user identity secret as a userIdentitySecret cookie parameter in your API requests.

Creating authentication credentials

Opaque requires SSO authentication. To use the API you need to obtain your API token:

1. Log in to the Opaque web application.
2. Navigate to API Keys in the left-hand nav and copy your API token.

The API token is valid for six months.

Obtaining refresh token and user identity secret

The API key is Base64-encoded and contains the required authentication tokens in JSON format. To extract the refresh token and user identity secret, decode the API key and retrieve the relevant fields from the API key:

import base64
import json

API_KEY = "your_base64_encoded_api_key"

# Decode the API key from Base64
api_key_decoded = base64.b64decode(API_KEY).decode("utf-8")

# Parse the JSON payload
api_key_dict = json.loads(api_key_decoded)

# Extract tokens
refresh_token = api_key_dict["refresh_token"]
user_identity_secret = api_key_dict["user_identity_secret"]

print(f"Refresh Token: {refresh_token}")
print(f"User Identity Secret: {user_identity_secret}")

Obtaining a session token from a refresh token

To generate a new session token and ID token using a refresh token, follow these steps:

1. Ensure you have a valid refresh token. The refresh token must be stored as an HttpOnly cookie named refreshTokenCookie. The API will automatically retrieve the refresh token from this cookie when making a request.
2. Make a request to the refresh token endpoint. Send a POST request to the /auth/refresh-token endpoint. If stored as a cookie, the refresh token is automatically included.

import requests

# Define the API URL (replace {version} with the appropriate API version)
API_URL = "https://your-opaque-api.com/v1/auth/refresh-token"

# Create a session and ensure the refresh token is stored as a cookie
session = requests.Session()
session.cookies.set("refreshTokenCookie", "your_refresh_token")

# Make the request to obtain a new session token and ID token
response = session.post(API_URL, timeout=30)

# Parse the response
if response.status_code == 200:
    data = response.json()
    session_token = data["accessToken"]
    print(f"Session Token: {session_token}")
else:
    print(f"Error: {response.status_code} - {response.text}")

Handling errors

Using authentication in API requests

The following sections provide guidance on how to use each type of authentication.

Using the refresh token

To maintain authentication and seamlessly renew session tokens, include the refresh token in API requests as an HttpOnly cookie named refreshTokenCookie. This ensures that when a session token expires, the system can automatically request a new one without requiring the user to log in again.

Example request

curl --request GET \
  --url http://api.opaque-client-api/v1.1/user \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <session_token>' \
  --header 'Cookie: refreshTokenCookie=<refresh_token>'

Using the session token

Session tokens authenticate API requests. Include them as bearer tokens or cookie-based authentication.

• Bearer token: Add to the Authorization header. For example, the following curl command requests information about the user associated with the session token:

curl --request GET \
  --url http://api.opaque-client-api/v1.1/user \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

Sample response

    {
  "email": "[email protected]"
  }

• Cookie-based authentication: For browser-based API calls (e.g., downloading results):

curl --request GET \
  --url http://api.opaque-client-api/v1.1/job/{job-uuid}/results \
  --header 'Accept: text/plain, application/json' \
  --header 'Cookie: sessionTokenCookie=<token>'

Using the user identity secret

For operations involving cryptographic data or sensitive APIs, include the userIdentitySecret in the Cookie header. The following curl example requests the creation of a two-party consortium (workspace) called Production-1:

curl --request POST \
  --url http://api.opaque-client-api/v1.1/consortium \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: userIdentitySecret=<API_key>' \
  --data '{
  "name": "Production-1",
  "members": [
    "[email protected]",
    "[email protected]"
  ]
}'

Sample response

{
  "createdBy": {
    "email": "[email protected]"
  },
  "members": [
    {
      "inviteStatus": "accepted",
      "member": {
        "email": "[email protected]"
      }
    },
    {
      "inviteStatus": "invited",
      "member": {
        "email": "[email protected]"
      }
    }
  ],
  "name": "Production-1",
  "status": "pending",
  "uuid": "a535ac2a-faf7-4b3d-b6b7-8c08ad1d8daf"
}