Authentication

The Collate API uses JWT (JSON Web Token) authentication. All API requests must include a valid token in the Authorization header.

Obtaining a Token

There are two ways to obtain an API token:

Bot Token (Recommended for Automation)

Bot tokens are ideal for service accounts, CI/CD pipelines, and automated integrations.

Note: The Bots tile under Settings is only visible to users with Admin privileges. If you don’t see it, ask your organization’s Collate Admin to generate a bot token for you or grant you Admin access.

Click the Profile icon and navigate to Settings > Bots.
Click Add Bot or select an existing bot.
Under Token, click Generate Token.
Copy and securely store the generated JWT token.

Important: Bot tokens have the permissions assigned to the bot’s role. Ensure the bot has appropriate roles for your use case.

Personal Access Token

Personal access tokens are tied to your user account and inherit your permissions.

Click the Profile icon and select your user name.
Click the Access Token tab.
Set the expiry time and click Generate Token.
Copy and save it securely for later use.

Note: Personal access tokens cannot be retrieved after creation. Store them securely immediately after generation.

Using the Token

Include the token in the Authorization header of all API requests:

Authorization: Bearer <your-jwt-token>

Examples

Token Example

from metadata.sdk import configure, Tables

# Configure with JWT token
configure(
    host="https://your-company.getcollate.io/api",
    jwt_token="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
)

# All subsequent calls are authenticated
tables = Tables.list_all()

import org.openmetadata.client.gateway.OpenMetadata;
import org.openmetadata.schema.services.connections.metadata.OpenMetadataConnection;
import org.openmetadata.schema.security.client.OpenMetadataJWTClientConfig;

// Configure with JWT token
OpenMetadataConnection config = new OpenMetadataConnection();
config.setHostPort("https://your-company.getcollate.io/api");
config.setAuthProvider(AuthProvider.OPENMETADATA);

OpenMetadataJWTClientConfig jwtConfig = new OpenMetadataJWTClientConfig();
jwtConfig.setJwtToken("eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...");
config.setSecurityConfig(jwtConfig);

// Create authenticated client
OpenMetadata client = new OpenMetadata(config);

# Include token in Authorization header
curl -X GET "https://your-company.getcollate.io/api/v1/tables" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Token Structure

Collate JWT tokens contain the following claims:

Claim	Description
`sub`	Subject - username or bot name
`iss`	Issuer - `open-metadata.org`
`roles`	Array of assigned roles
`email`	User or bot email
`isBot`	Boolean indicating if token is for a bot
`tokenType`	`BOT` or `PERSONAL_ACCESS`
`iat`	Issued at timestamp
`exp`	Expiration timestamp (null for non-expiring bot tokens)

Example decoded token payload:

{
  "iss": "open-metadata.org",
  "sub": "ingestion-bot",
  "roles": ["IngestionBotRole"],
  "email": "ingestion-bot@open-metadata.org",
  "isBot": true,
  "tokenType": "BOT",
  "iat": 1704067200,
  "exp": null
}

Authentication Errors

Error	Status Code	Description
Missing token	`401`	No Authorization header provided
Invalid token	`401`	Token is malformed or signature invalid
Expired token	`401`	Token has passed its expiration time
Insufficient permissions	`403`	Token lacks required role/permission

Error Response Format

{
  "code": 401,
  "message": "Token has expired"
}

Security Best Practices

Use bot tokens for automation: Create dedicated bot accounts for each integration rather than using personal tokens.
Rotate tokens regularly: Set expiration dates on personal access tokens and rotate bot tokens periodically.
Apply least privilege: Assign only the minimum required roles to bots and service accounts.
Store tokens securely: Use environment variables or secret managers. Never commit tokens to source control.
Monitor token usage: Review audit logs to track API usage and detect anomalies.

Environment Variables

For convenience, you can configure authentication using environment variables:

# Set your Collate host
export OPENMETADATA_HOST=https://your-company.getcollate.io/api

# Set your JWT token
export OPENMETADATA_JWT_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

from metadata.sdk import configure, Tables

# configure() reads OPENMETADATA_HOST and OPENMETADATA_JWT_TOKEN from env
configure()

tables = Tables.list_all()

SSO Integration

Collate supports SSO authentication providers for the UI. For API access, you still need to use JWT tokens, but users authenticated via SSO can generate personal access tokens from their profile. Supported SSO providers:

Okta
Azure AD
Google
Auth0
Custom OIDC
SAML
LDAP

SSO Configuration

Configure Single Sign-On for your organization

​Authentication

​Obtaining a Token

​Bot Token (Recommended for Automation)

​Personal Access Token

​Using the Token

​Examples

​Token Structure

​Authentication Errors

​Error Response Format

​Security Best Practices

​Environment Variables

​SSO Integration

SSO Configuration

Authentication

Obtaining a Token

Bot Token (Recommended for Automation)

Personal Access Token

Using the Token

Examples

Token Structure

Authentication Errors

Error Response Format

Security Best Practices

Environment Variables

SSO Integration