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

Optional 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. We recommend including timestamp_nonce in all authentication requests when possible for enhanced security.

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

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

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 an optional property to ensure backwards compatibility. For enhanced security, you can configure Rustici Generator to require timestamp_nonce for all authentication requests:

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

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. This lifespan is 1 hour by default, but can be configured according to your teams’ preferences. 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.