API Authentication

Catalio uses OAuth 2.0 for API authentication. This guide covers how to create credentials and authenticate your requests.

Quick Start

1. Create API Credentials

Organization administrators can create API credentials in the Catalio web application:

Navigate to Settings → API Credentials
Click Create Credential
Enter a descriptive name (e.g., “CI/CD Pipeline” or “Data Sync”)
Click Create

Important

The client_secret is shown only once. Copy and store it securely immediately.

2. Get an Access Token

Exchange your credentials for an access token:

Bash

curl -X POST https://catalio.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://catalio.ai/api/v1",
    "grant_type": "client_credentials"
  }'

Response:

Json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Tokens are valid for 24 hours.

3. Make Authenticated Requests

Include your access token in the Authorization header:

Bash

curl -X GET https://catalio.ai/api/v1/requirements \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/vnd.api+json"

For available endpoints and usage examples, see the JSON:API Overview.

Managing Credentials

Viewing Credentials

Navigate to Settings → API Credentials to see all credentials for your organization, including when each was created and last used.

Rotating Secrets

If a credential may have been compromised:

Click Rotate next to the credential
Copy the new client_secret immediately

Warning

Rotating invalidates the previous secret immediately. Update your systems before rotating.

Revoking Credentials

To permanently revoke a credential, click Revoke. Revoked credentials cannot be restored.

Error Responses

Code	Meaning
`401`	Invalid, missing, or expired token
`403`	Insufficient permissions for the requested resource
`404`	Resource not found

Example error response:

Json

{
  "errors": [
    {
      "status": "401",
      "title": "Unauthorized",
      "detail": "Invalid or expired token"
    }
  ]
}

Security Best Practices

Create separate credentials for each integration (CI/CD, monitoring, etc.)
Rotate secrets regularly (e.g., every 90 days)
Store secrets securely in environment variables or a secrets manager
Revoke unused credentials promptly

Next Steps

JSON:API Overview — Available resources and usage examples
Swagger Documentation — Interactive API explorer