API Authentication

API Authentication

Rustici Generator uses bearer tokens for API authentication. Before making API requests to protected endpoints, you must obtain an access token by authenticating with your credentials This page covers the authentication process and best practices for managing access tokens.

Authentication Process

Almost all API requests to Rustici Generator require authentication using Bearer tokens. To obtain an access token, you must first authenticate using the /api/v1/login/access_token endpoint with valid credentials.

Authentication Endpoint

Endpoint: POST /api/v1/login/access_token

Content-Type: application/x-www-form-urlencoded

Parameters:

  • timestamp_nonce (Integer, Unix timestamp in seconds): A timestamp-based nonce that prevents replay attacks. The nonce must be within a configurable time window of the server’s current time, and each credential can only use a nonce value once (each new value must be strictly greater than the last). Clients should send the current Unix time in seconds. By default this field is required; set SECURITY__NONCE_REQUIRED=false to make it optional.

Resource

Tokens can be generated for either the API_V1 or MCP resource. Set the resource form field on the login request. If resource is omitted, the token is minted for API_V1.

  • API_V1 is the traditional REST API. Use these tokens for application integrations.
  • MCP is Generator’s MCP server. Use these tokens when connecting an LLM client. See the MCP Integration page for connection details, tools, and resources.

Tokens are audience-bound: an API_V1 token is rejected by MCP tools and resources, and an MCP token is rejected by the API endpoints.

curl -X 'POST' \
'https://[DOMAIN]/api/v1/login/access_token' \
-H 'accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-raw 'grant_type=password&username=[CREDENTIAL_ID]&password=[CREDENTIAL_PASSWORD]&resource=API_V1&timestamp_nonce=1735689600'

Grant Types

Rustici Generator supports two OAuth 2.0 grant types for authentication:

Password Grant Type

Use this grant type when authenticating with username and password credentials.

Required Parameters:

  • grant_type: Must be set to password
  • username: Your credential ID
  • password: Your credential password
  • timestamp_nonce: Current Unix time in seconds (unless SECURITY__NONCE_REQUIRED=false)

Example Request:

curl -X 'POST' \
'https://[DOMAIN]/api/v1/login/access_token' \
-H 'accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-raw 'grant_type=password&username=[CREDENTIAL_ID]&password=[CREDENTIAL_PASSWORD]&timestamp_nonce=1735689600'

Client Credentials Grant Type

Use this grant type for service-to-service authentication using client credentials.

Required Parameters:

  • grant_type: Must be set to client_credentials
  • client_id: Your credential ID
  • client_secret: Your credential password
  • timestamp_nonce: Current Unix time in seconds (unless SECURITY__NONCE_REQUIRED=false)

Example Request:

curl -X 'POST' \
'https://[DOMAIN]/api/v1/login/access_token' \
-H 'accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-raw 'grant_type=client_credentials&client_id=[CREDENTIAL_ID]&client_secret=[CREDENTIAL_PASSWORD]&timestamp_nonce=1735689600'

Requiring timestamp_nonce

By default, timestamp_nonce is required on all authentication requests. To restore the previous optional behavior:

  • Self-hosted instances: Set the SECURITY__NONCE_REQUIRED environment variable to false (see Hosting Variables for details)
  • Managed hosting customers: Contact Rustici Software support if you need this requirement disabled for your instance

Access Control Policies

Access Control Policies can be attached to a token being generated for the MCP resource. Policies are a composite of Access Control Targets, which are groups of content within a tenant. The policy limits which content the token bearer can search and read — useful when an LLM client should see only a subset of a tenant’s catalog rather than everything the credential can access.

To attach a policy, provide access_control_policy_id and tenant_id on the authentication request. tenant_id is required when a policy is specified. Access control policies are not allowed on API_V1 tokens.

curl -X 'POST' \
'https://[DOMAIN]/api/v1/login/access_token' \
-H 'accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-raw 'grant_type=password&username=[CREDENTIAL_ID]&password=[CREDENTIAL_PASSWORD]&resource=MCP&tenant_id=[TENANT_ID]&access_control_policy_id=[POLICY_ID]&timestamp_nonce=1735689600'

To learn more about Access Control Policies, see Access Control Targets and Policies .

Authentication Response

Upon successful authentication, the API returns a JSON response containing your access token and additional metadata:

{
  "access_token": "your_access_token_here",
  "token_type": "bearer"
}

Response Properties:

  • access_token: The Bearer token to use for authenticated API requests
  • token_type: Always “bearer” for Rustici Generator

Using Access Tokens

Once you have obtained an access token, include it in the Authorization header of your API requests using the Bearer token format:

curl -X 'GET' \
'https://[domain]/api/v1/jobs' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [ACCESS_TOKEN]'

Token Management

Token Expiration

Access tokens have a limited lifetime. API tokens expire after SECURITY__ACCESS_TOKEN_EXPIRE_MINUTES and MCP tokens expire after SECURITY__MCP_ACCESS_TOKEN_EXPIRE_MINUTES (both default to 60 minutes). When a token expires, you will receive a 403 Forbidden response. You must obtain a new access token by re-authenticating with the login endpoint.