Authentication

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

Navigate to Settings > Bots in the OpenMetadata UI
Click Add Bot or select an existing bot
Under Token, click Generate Token
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.

Click your profile icon in the top-right corner
Select Access Tokens
Click Generate New Token
Set an expiration date and click Generate
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.sdk import configure

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

# All subsequent SDK calls are now authenticated
from metadata.sdk import Tables
for table in Tables.list().auto_paging_iterable():
    print(table.name)

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.open-metadata.org/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.open-metadata.org/api/v1/tables" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Token Structure

OpenMetadata 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 OpenMetadata host
export OPENMETADATA_HOST=https://your-company.open-metadata.org/api

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

from metadata.sdk import configure

# Reads from OPENMETADATA_HOST and OPENMETADATA_JWT_TOKEN automatically
configure()

SSO Integration

OpenMetadata 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