Skip to main content

OAuth API Authentication

OAuth API Authentication enables secure, programmatic access to the Breeze API using industry-standard OAuth 2.0 tokens. This authentication method is designed for machine-to-machine integrations, automated systems, and service-to-service communication where applications need to access the API without user interaction.

When to Use This​

Use OAuth API Authentication when you need to:

  • Integrate external systems with Breeze programmatically
  • Build automated workflows that access the API
  • Create service-to-service integrations
  • Access the API from scripts, scheduled jobs, or background services
  • Replace API key authentication with a more secure, standards-based approach

This authentication method is ideal for:

  • Payment processor integrations
  • Automated reporting systems
  • CI/CD pipeline integrations
  • Partner API access
  • Mobile or desktop application backends

Before You Start​

To use OAuth API Authentication, you need:

  • OAuth Client Credentials: A client_id and client_secret obtained from an administrator (see OAuth Client Management)
  • API Access: The OAuth client must be associated with a user account that has appropriate roles for your required operations
  • HTTPS Connection: Always use HTTPS in production environments
Required for Setup

Creating OAuth Clients: Only users with Super administrator role can create OAuth clients. See OAuth Client Management for more information.

How OAuth Authentication Works​

OAuth API Authentication uses the OAuth 2.0 Client Credentials flow, which is designed for machine-to-machine communication. Here's how it works:

Overview​

  1. Obtain Credentials: Get client_id and client_secret (see OAuth Client Management)
  2. Request Access Token: Exchange credentials for a short-lived access token
  3. Use Access Token: Include the token in API requests to authenticate
  4. Refresh Token: Request a new token before expiration (tokens cannot be refreshed)

Step 1: Obtain OAuth Client Credentials​

  1. Create an OAuth client associated with a user account
  2. Provide you with:
    • Client ID: A unique identifier (format: oauth_xxx)
    • Client Secret: A secure secret string (shown only once during creation)

Important: Store these credentials securely. Never commit them to version control or share them insecurely.

Step 2: Request an Access Token​

To authenticate, send a POST request to the token endpoint:

Endpoint: POST /oauth/token

Request Format:

{
  "grant_type": "client_credentials",
  "client_id": "oauth_abc123...",
  "client_secret": "your_secret_here",
  "scope": "read:credentials write:credentials"
}

Parameters:

  • grant_type: Must be "client_credentials" (required)
  • client_id: Your OAuth client ID (required)
  • client_secret: Your OAuth client secret (required)
  • scope: Optional space-separated list of scopes (permissions are determined by the user's roles, not scopes)

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": ""
}

Response Fields:

  • access_token: JWT token to use for API authentication (valid for 1 hour by default)
  • token_type: Always "Bearer"
  • expires_in: Token lifetime in seconds (default: 3600 = 1 hour)
  • scope: Space-separated list of granted scopes

Step 3: Use the Access Token​

Include the access token in all API requests using the Authorization header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Example API Request:

curl https://api.domain.com/graphql \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"query": "{ CredentialV1(credentialId: \"...\") { _id name } }"}'

Step 4: Handle Token Expiration​

Access tokens expire after 1 hour (default). Before expiration:

  1. Request a New Token: Use the same /oauth/token endpoint with your client credentials
  2. Update Your Application: Replace the old token with the new one
  3. Implement Token Caching: Cache tokens and refresh them proactively (e.g., 5 minutes before expiration)

Best Practice: Request a new token before the current one expires to avoid service interruption.

Permissions and Authorization​

How Permissions Work​

OAuth client permissions are determined by the user account associated with the client, not by OAuth scopes. When the an OAuth client is created, it is associated with a specific user account. The client inherits all permissions from that user's roles.

Important: The OAuth client can only access resources within the tenant of the associated user account.

OAuth Scopes​

OAuth scopes are currently not used for permissions. They are reserved for future use.

Token Management Best Practices​

Token Caching​

  • Cache tokens to reduce token requests and improve performance
  • Track expiration and refresh tokens proactively (5 minutes before expiration)
  • Store tokens securely in memory or secure storage (never in logs or error messages)

Error Handling​

  • Handle token expiration: Implement automatic token refresh when you receive 401 Unauthorized responses
  • Handle rate limits: If you receive 429 Too Many Requests, implement exponential backoff
  • Log errors appropriately: Never log tokens or client secrets

Security​

  • Store secrets securely: Use environment variables or secret management systems
  • Rotate secrets: Rotate client secrets regularly (every 90 days recommended)
  • Monitor usage: Track token usage and authentication failures

Rate Limiting​

The OAuth token endpoint has rate limiting to prevent abuse:

  • Default limit: 100 requests per hour per client
  • Window: 1 hour (3600 seconds)
  • Tracking: Per client_id

Best Practices:

  • Implement token caching to minimize token requests
  • Reuse tokens until expiration
  • If you hit rate limits, reduce request frequency or contact support for custom limits

Common Issues and Solutions​

"Invalid client credentials"​

Possible causes:

  • Incorrect client_id or client_secret
  • Client has been revoked or is inactive
  • Client secret has been rotated (use the latest secret)

Solutions:

  • Verify credentials are correct (no extra spaces or encoding issues)
  • Check with your administrator that the client is active
  • Request new credentials if the secret was rotated

"Token validation failed"​

Possible causes:

  • Token has expired
  • Incorrect Authorization header format
  • Token signature is invalid

Solutions:

  • Request a new token (tokens expire after 1 hour)
  • Ensure header format is: Authorization: Bearer <token>
  • Verify you're using the latest token

"Rate limit exceeded"​

Possible causes:

  • Too many token requests in a short time
  • Not caching tokens between requests

Solutions:

  • Implement token caching
  • Reduce token request frequency
  • Wait for the rate limit window to reset (1 hour)

"Insufficient permissions"​

Possible causes:

  • Associated user account lacks required roles
  • User account has been deactivated
  • Accessing resources outside the user's tenant

Solutions:

  • Verify the associated user account has the required roles
  • Check with your administrator to update user roles if needed
  • Ensure you're accessing resources within the correct tenant

What's Next?​