Authentication API

Base URL: https://authenticate.opteryx.app

Overview

Authentication, OAuth 2.0, OpenID Connect discovery, JWKS publication, and client credential management.

Getting a token

Every other Opteryx API expects a bearer token. Getting one is a two-part conversation: create a credential once, then exchange it for access tokens as often as you need.

• The secret is shown once. CreateCredentialResponse.secret is only ever returned at creation time — store it immediately. If it's lost, revoke the credential and create a new one; there's no way to retrieve it again.
• Prefer refresh over the client secret when you have it. If /token returned a refresh_token, use grant_type=refresh_token to rotate access tokens without touching the stored client_secret again.
• Tokens are bearer, not sessions. There's no separate "login" call — holding a valid access_token is what authenticates every request to Upload, Jobs, and Policy.

Endpoints

List Credentials

Request: get/clients/{client_id}/credentials

Tags: credentials

List all active credentials for a client (without secrets).

Args: client_id: Client identifier

Returns: List of credential metadata (excluding secrets)

Path Parameters

• client_id string [path; required] Client identifier

Header Parameters

• authorization string | null [header; optional]
• x-admin-token string | null [header; optional]

Responses

• 200 — Successful Response (application/json array<CredentialMetadata>)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Create Credential

Request: post/clients/{client_id}/credentials

Tags: credentials

Create a new client credential (PAT).

This creates a Personal Access Token (PAT) for machine-to-machine authentication. The secret is shown only once and must be stored securely by the caller.

Callers may create credentials for their own client_id (authenticated via bearer token) or, with an admin token, for any client_id.

Args: client_id: Client identifier request: Credential creation parameters

Returns: Credential metadata with plaintext secret (shown only once)

Path Parameters

• client_id string [path; required] Client identifier

Header Parameters

• authorization string | null [header; optional]
• x-admin-token string | null [header; optional]

Request Body

• Content-Type: application/json Schema: CreateCredentialRequest
  • type string [optional] Credential type: 'interactive', or a named identifier for a machine credential. Default: interactive
  • expires_in_days integer | null [optional] Lifetime of the credential in days. Pass null for a credential that never expires. Default: 90
  • scopes array<string> [optional] Scopes to grant the credential. Empty grants the caller's default scopes.
  • permissions array<array<string>> [optional] Resource grants as [pattern, role] pairs, e.g. [['analytics.*', 'reader']]. Roles are 'owner', 'admin', 'writer' or 'reader'.

Responses

• 200 — Successful Response (application/json CreateCredentialResponse)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Revoke Credential

Request: delete/clients/{client_id}/credentials/{credential_id}

Tags: credentials

Revoke a credential by deleting it.

Args: client_id: Client identifier credential_id: Credential ID to revoke

Returns: Success message

Path Parameters

• client_id string [path; required] Client identifier
• credential_id string [path; required] Credential ID to revoke

Header Parameters

• authorization string | null [header; optional]
• x-admin-token string | null [header; optional]

Responses

• 200 — Successful Response (application/json object)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Get signing keys

Request: get/jwks

Tags: authentication

Returns the JSON Web Key Set used to verify access tokens issued by this service.

Responses

• 200 — Successful Response (application/json object)

Try it live

Get current user

Request: get/me

Validates the bearer token and returns the caller identity, billing account and token scope details.

Header Parameters

• authorization string | null [header; optional]

Responses

• 200 — Successful Response (application/json object)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Issue an access token

Request: post/token

Tags: authentication

Creates access tokens for client credentials or refresh-token exchanges used by customer integrations.

Query Parameters

• set_cookie boolean [query; optional] Default: false

Request Body

• Content-Type: application/x-www-form-urlencoded Schema: Body_token_endpoint_token_post
  • grant_type string [optional] Default: client_credentials
  • client_id string [optional]
  • client_secret string [optional]
  • refresh_token string [optional]

Responses

• 200 — Successful Response (application/json TokenResponse)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live