Authentication Tokens

The Vertesia Security Token Service (STS) provides endpoints for generating JWT tokens that authenticate subsequent API calls.

The /token/issue endpoint supports multiple token types and authentication methods.
The legacy /auth/token endpoint provides backward compatibility for simple API key-to-token conversion.

The STS endpoints are public APIs and not part of the protected API accessible through the /api/v1 root.
API keys provide full access to your account - treat them like passwords
Consider using short-lived tokens that expire for enhanced security
Use the audience parameter to restrict which services can accept your tokens

Issue Token

The token issuance endpoint supports multiple token types and enterprise-grade authentication methods with fine-grained control over token generation.

Host: https://sts.vertesia.io (dedicated Security Token Service)

Endpoint: /token/issue

Method: POST

Requirements: Requires valid API key, Firebase token, or JWT token for authentication.

Headers

Header	Value	Description
Authorization	`Bearer <YOUR_API_KEY> \| Bearer <YOUR_FIREBASE_TOKEN> \| Bearer <YOUR_JWT_TOKEN>`	(Required) Vertesia API key, Firebase authentication token, or Vertesia JWT token (for token exchange/refresh)

Common Parameters (All Token Types)

Parameter	Data Type	Description
type	`string`	Token type to generate. Must be one of: apikey, user, project, environment, agent, service_account.
audience	`string`	Target audience for the token. Controls which services can accept the token.
algorithm	`string`	Signing algorithm: ES256 (default) or RS256. Use RS256 for Azure AD compatibility.

API Key Token Parameters (type: "apikey")

Parameter	Data Type	Description
key	`string`	The API key to convert to a JWT token. Account and project are determined from the key.

User Token Parameters (type: "user")

Parameter	Data Type	Description
user_id	`string`	User ID. If not specified, determined from the authentication token.
account_id	`string`	The ID of the account to scope the token to.
project_id	`string`	The ID of the project to scope the token to.
expires_at	`number`	Token expiration timestamp (Unix epoch). If not specified, uses default expiration.
on_behalf_of	`string`	User ID when acting on behalf of another user.

Agent Token Parameters (type: "agent")

Parameter	Data Type	Description
account_id	`string`	(Required) The ID of the account the agent operates under.
project_id	`string`	(Required) The ID of the project the agent operates in. Verified to belong to the specified account.
on_behalf_of	`string`	(Required) A valid signed Vertesia JWT token representing the user the agent acts on behalf of. Provides user context for the agent.
name	`string`	Descriptive name for the agent (e.g., "My AI Assistant").

Project Token Parameters (type: "project")

Parameter	Data Type	Description
project_id	`string`	(Required) The ID of the project to scope the token to.
account_id	`string`	(Required) The ID of the account that owns the project.

Environment Token Parameters (type: "environment")

Parameter	Data Type	Description
environment_id	`string`	(Required) The ID of the environment (dev, staging, production, etc.).
environment_name	`string`	(Required) The name of the environment. Required as environments may not be in the database.
project_id	`string`	(Required) The ID of the project the environment belongs to. Name and account verification performed automatically.
account_id	`string`	(Required) The ID of the account that owns the environment. Verified to ensure project belongs to this account.

Service Account Token Parameters (type: "service_account")

Parameter	Data Type	Description
account_id	`string`	(Required) The ID of the account the service account belongs to.
project_id	`string`	(Required) The ID of the project the service account operates in. Verified to belong to the specified account.
name	`string`	Descriptive name for the service account (e.g., "Data Sync Service").
roles	`string[]`	Array of role names assigned to the service account token for authorization purposes.

Response Fields

Field	Type	Description
token	`string`	The generated JWT token
token_type	`string`	Token type (always "Bearer")
expires_in	`number`	Token validity duration in seconds

Code Examples

Issue JWT Token for API Key

curl --location --request POST \
  'https://sts.vertesia.io/token/issue' \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Issue JWT Token for User

curl --location --request POST \
  'https://sts.vertesia.io/token/issue' \
  --header 'Authorization: Bearer <YOUR_FIREBASE_TOKEN>' \
  --data-raw '{
    "type": "user",
    "account_id": "<ACCOUNT_ID>",
    "project_id": "<PROJECT_ID>"
    }'

Auth Token (legacy)

The following legacy endpoint is maintained for backward compatibility and supports exchanging a Vertesia API key or a Firebase authentication token for a Vertesia JWT token.

New implementations should use the /token/issue endpoint.

Hosts: https://sts.vertesia.io (dedicated Security Token Service) or https://api.vertesia.io (API proxy to Security Token Service)

Endpoint: /auth/token

Methods: GET or POST

Both methods are functionally identical - the only difference is parameter passing:

GET: Parameters passed as query string parameters
POST: Parameters passed in request body (JSON)

Requirements: Requires valid API key or Firebase token for authentication.

Headers

Header	Value	Description
Authorization	`Bearer <YOUR_API_KEY> \| Bearer <FIREBASE_TOKEN>`	(Required) Vertesia API key or Firebase authentication token

Parameters

These can be passed as query parameters (GET) or in the request body (POST):

Parameter	Data Type	Description
audience	`string`	Target audience for the token. Controls which services can accept the token.
project_id	`string`	The ID of the project to scope the token to. If not specified, uses the project associated with the API Key.
account_id	`string`	The ID of the account to scope the token to. If not specified, uses the account associated with the API Key.
expires_at	`string`	Custom expiration timestamp (ISO 8601 format). If not specified, uses default token expiration.
algorithm	`string`	Signing algorithm to use. Allowed values: `ES256` (default), `RS256`.

Response Fields

Field	Type	Description
token	`string`	The generated JWT token
token_type	`string`	Token type (always "Bearer")
expires_in	`number`	Token validity duration in seconds

Code Examples

Get a JWT token using an API Key.

Get JWT Token

curl --location --request GET \
  'https://api.vertesia.io/auth/token' \
  --header 'Authorization: Bearer <YOUR_API_KEY>'