Authentication

The Thirdfort Client API uses OAuth 2.0 Bearer tokens for authentication. All API requests must include a valid access token in the Authorization header.

Overview

Thirdfort uses the OAuth 2.0 Client Credentials flow for machine-to-machine authentication. This is ideal for server-side integrations where your application acts on its own behalf.

Prerequisites

Before you can authenticate, you need:

1. Client ID - Your application's unique identifier
2. Client Secret - Your application's secret key (keep this secure!)
3. API Access - Confirm your account has been provisioned for API access

Contact your Thirdfort account manager or email api-support@thirdfort.com to obtain credentials.

Obtaining Tokens

Request tokens from the token endpoint using your client ID and secret.

Token Request:

curl -X POST https://creative-jungle-73-staging.authkit.app/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Successful Response:

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

Using Tokens

Include the access token in the Authorization header of every API request:

curl -X GET https://api.thirdfort.dev/client/api/v1alpha2/organizations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Token Lifetime

• Expiry: Tokens expire after one hour (3600 seconds)
• Refresh: Request a new token before the current one expires
• Caching: Cache tokens and reuse them until near expiry to reduce the number of token endpoint requests

Recommended Token Management

It is likely that your preferred language has a library that can handle token management for you. However, if you are implementing token management yourself, the following example may be helpful.

import time
import requests

class TokenManager:
    def __init__(self, client_id, client_secret):
        self.client_id = client_id
        self.client_secret = client_secret
        self.token = None
        self.expires_at = 0

    def get_token(self):
        # Refresh if token expires in less than 5 minutes
        if time.time() > self.expires_at - 300:
            self._refresh_token()
        return self.token

    def _refresh_token(self):
        response = requests.post(
            "https://creative-jungle-73-staging.authkit.app/oauth2/token",
            data={
                "grant_type": "client_credentials",
                "client_id": self.client_id,
                "client_secret": self.client_secret
            }
        )
        response.raise_for_status()
        data = response.json()
        self.token = data["access_token"]
        self.expires_at = time.time() + data["expires_in"]

Error Handling

Common Authentication Errors

Status Code	Error	Description
401	Unauthorized	Token missing, expired, or invalid
403	Forbidden	Token valid but lacks required permissions

Example Error Response

HTTP 401 Unauthorized

{
    "code": "unauthenticated",
    "message": "unable to authenticate"
}