Skip to main content

​
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 tokens are ideal for service accounts, CI/CD pipelines, and automated integrations.
  1. Navigate to Settings > Bots in the Collate UI
  2. Click Add Bot or select an existing bot
  3. Under Token, click Generate Token
  4. Copy and securely store the generated JWT token
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.
  1. Click your profile icon in the top-right corner
  2. Select Access Tokens
  3. Click Generate New Token
  4. Set an expiration date and click Generate
  5. Copy and securely store the token
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.ingestion.ometa.ometa_api import OpenMetadata
from metadata.generated.schema.entity.services.connections.metadata.openMetadataConnection import (
    OpenMetadataConnection,
)
from metadata.generated.schema.security.client.openMetadataJWTClientConfig import (
    OpenMetadataJWTClientConfig,
)

# Configure with JWT token
server_config = OpenMetadataConnection(
    hostPort="https://your-company.getcollate.io/api",
    authProvider="openmetadata",
    securityConfig=OpenMetadataJWTClientConfig(
        jwtToken="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
    ),
)

# Create authenticated client
metadata = OpenMetadata(server_config)

# All subsequent calls are authenticated
tables = metadata.list_all_entities(entity=Table)

​
Token Structure

Collate JWT tokens contain the following claims:
ClaimDescription
subSubject - username or bot name
issIssuer - open-metadata.org
rolesArray of assigned roles
emailUser or bot email
isBotBoolean indicating if token is for a bot
tokenTypeBOT or PERSONAL_ACCESS
iatIssued at timestamp
expExpiration timestamp (null for non-expiring bot tokens)
Example decoded token payload: 
{
  "iss": "open-metadata.org",
  "sub": "ingestion-bot",
  "roles": ["IngestionBotRole"],
  "email": "[email protected]",
  "isBot": true,
  "tokenType": "BOT",
  "iat": 1704067200,
  "exp": null
}

​
Authentication Errors

ErrorStatus CodeDescription
Missing token401No Authorization header provided
Invalid token401Token is malformed or signature invalid
Expired token401Token has passed its expiration time
Insufficient permissions403Token lacks required role/permission

​
Error Response Format

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

​
Security Best Practices

1

Use Bot Tokens for Automation

Create dedicated bot accounts for each integration rather than using personal tokens.
2

Rotate Tokens Regularly

Set expiration dates on personal access tokens and rotate bot tokens periodically.
3

Apply Least Privilege

Assign only the minimum required roles to bots and service accounts.
4

Store Tokens Securely

Use environment variables or secret managers. Never commit tokens to source control.
5

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...

​
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