Authentication

Cohera supports multiple authentication methods to fit different use cases. Choose the method that best fits your application.

Authentication Methods

Method	Best For	Security Level
API Keys	Server-to-server, scripts, CLI	High
OAuth2	User-facing applications	Highest
JWT Tokens	Microservices, short-lived access	High

API Keys

API keys are the simplest way to authenticate with Cohera. They’re ideal for server-side applications, scripts, and development.

Creating an API Key

1. Log in to your Cohera Dashboard
2. Go to Settings > API Keys
3. Click Create New Key
4. Select the appropriate scopes
5. Set an expiration date (optional but recommended)
6. Copy and securely store the key

Using API Keys

Python

from cohera import Cohera

# Via environment variable (recommended)
import os
os.environ["COHERA_API_KEY"] = "ck_live_..."
client = Cohera()

# Via constructor
client = Cohera(api_key="ck_live_...")

TypeScript

import { Cohera } from '@cohera/sdk';

// Via environment variable (recommended)
const client = new Cohera();
// Reads from COHERA_API_KEY

// Via constructor
const client = new Cohera({ apiKey: 'ck_live_...' });

cURL

curl -X GET "https://api.cohera.io/v1/certificates" \
  -H "Authorization: Bearer ck_live_..."

API Key Scopes

Control what your API key can access:

Scope	Description
read:certificates	Read certificate data
write:certificates	Create and update certificates
read:suppliers	Read supplier data
write:suppliers	Create and update suppliers
read:products	Read product data
write:products	Create and update products
admin	Full access to all resources

Tip

Follow the principle of least privilege. Only grant the scopes your application needs.

OAuth2

OAuth2 is recommended for applications that act on behalf of users. It provides the highest level of security and allows users to control their data access.

OAuth2 Flow

┌──────────┐     ┌──────────┐     ┌──────────┐
│   User   │────>│ Your App │────>│  Cohera  │
└──────────┘     └──────────┘     └──────────┘
     │                │                │
     │  1. Login      │                │
     │───────────────>│                │
     │                │  2. Redirect   │
     │                │───────────────>│
     │                │                │
     │  3. Authorize  │<───────────────│
     │<───────────────│                │
     │                │                │
     │                │  4. Token      │
     │                │<───────────────│
     │                │                │
     │  5. Access     │                │
     │<───────────────│                │
└──────────────────────────────────────┘

Setting Up OAuth2

1. Register your application in the Developer Console
2. Configure your redirect URIs
3. Note your Client ID and Client Secret
4. Implement the authorization flow

Implementation

Python

from cohera import Cohera
from cohera.auth import OAuth2

# Step 1: Get authorization URL
oauth = OAuth2(
    client_id="your-client-id",
    client_secret="your-client-secret",
    redirect_uri="https://yourapp.com/callback"
)

auth_url = oauth.get_authorization_url(
    scopes=["read:certificates", "read:suppliers"]
)
# Redirect user to auth_url

# Step 2: Handle callback
code = request.args.get("code")  # From callback
tokens = oauth.exchange_code(code)

# Step 3: Use the access token
client = Cohera(access_token=tokens.access_token)
certificates = client.certificates.list()

# Step 4: Refresh when needed
if tokens.is_expired:
    tokens = oauth.refresh_token(tokens.refresh_token)

TypeScript

import { Cohera, OAuth2 } from '@cohera/sdk';

// Step 1: Get authorization URL
const oauth = new OAuth2({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  redirectUri: 'https://yourapp.com/callback'
});

const authUrl = oauth.getAuthorizationUrl({
  scopes: ['read:certificates', 'read:suppliers']
});
// Redirect user to authUrl

// Step 2: Handle callback
const code = req.query.code; // From callback
const tokens = await oauth.exchangeCode(code);

// Step 3: Use the access token
const client = new Cohera({ accessToken: tokens.accessToken });
const certificates = await client.certificates.list();

// Step 4: Refresh when needed
if (tokens.isExpired) {
  const newTokens = await oauth.refreshToken(tokens.refreshToken);
}

JWT Tokens

JWT tokens are used for service-to-service authentication and short-lived access. They’re signed tokens that contain claims about the authenticated entity.

Generating a JWT

Python

from cohera import Cohera
from cohera.auth import ServiceAccount

# Load service account credentials
sa = ServiceAccount.from_file("service-account.json")

# Generate a JWT
token = sa.generate_token(
    scopes=["read:certificates"],
    expires_in=3600  # 1 hour
)

# Use the token
client = Cohera(access_token=token)

TypeScript

import { Cohera, ServiceAccount } from '@cohera/sdk';
import { readFileSync } from 'fs';

// Load service account credentials
const sa = ServiceAccount.fromFile('service-account.json');

// Generate a JWT
const token = await sa.generateToken({
  scopes: ['read:certificates'],
  expiresIn: 3600 // 1 hour
});

// Use the token
const client = new Cohera({ accessToken: token });

JWT Structure

Cohera JWTs contain the following claims:

{
  "iss": "cohera.io",
  "sub": "sa_abc123",
  "aud": "https://api.cohera.io",
  "exp": 1699999999,
  "iat": 1699996399,
  "scopes": ["read:certificates", "read:suppliers"],
  "org_id": "org_xyz789"
}

Security Best Practices

Security Checklist

Follow these practices to keep your credentials secure:

1. Never commit credentials - Use environment variables or secret managers
2. Rotate keys regularly - Set expiration dates and rotate keys periodically
3. Use least privilege - Only request scopes your application needs
4. Monitor usage - Review API key usage in the dashboard
5. Revoke unused keys - Delete keys that are no longer needed

Environment Variables

# .env file (never commit this!)
COHERA_API_KEY=ck_live_...
COHERA_CLIENT_ID=your-client-id
COHERA_CLIENT_SECRET=your-client-secret

Secret Managers

We recommend using a secret manager in production:

• AWS Secrets Manager
• Google Secret Manager
• HashiCorp Vault
• Azure Key Vault

Rate Limiting

All authentication methods are subject to rate limits:

Tier	Requests/min	Requests/day
Free	60	1,000
Pro	600	50,000
Enterprise	Custom	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1699999999

Next Steps

• Quickstart - Make your first API call
• Python SDK - Full Python SDK documentation
• API Reference - Complete API documentation