### Bearer Token Authentication Example

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

This bash snippet shows how to authenticate using a Bearer token with the Circle.so API. It includes an example API call for obtaining an auth token and demonstrates a typical 401 Unauthorized response.

```bash
# Standard request with Bearer authentication:
curl -X POST https://app.circle.so/api/v1/headless/auth_token \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sso_user_id": "abc123"}'

# Unauthorized Response (401):
{
  "success": false,
  "message": "Your account could not be authenticated.",
  "error_details": {}
}
```

--------------------------------

### Authenticate with Email and Make API Request (Python)

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

This snippet demonstrates authenticating with the Circle.so API using an email address, retrieving an access token and community ID, ensuring the token is valid, and then making an authenticated GET request to a Circle API endpoint. It also includes error handling for token cleanup.

```python
import requests

# Assuming 'client' is an initialized Circle API client object
# For example: from circle.client import CircleClient
# client = CircleClient(api_key='YOUR_API_KEY')

# Authenticate with email
auth_data = client.authenticate('user@example.com')
print(f"Access Token: {auth_data['access_token']}")
print(f"Community ID: {auth_data['community_id']}")

# Ensure valid token before making requests
valid_token = client.ensure_valid_access_token()

# Make API request with access token
api_response = requests.get(
    'https://app.circle.so/api/v1/some_endpoint',
    headers={'Authorization': f'Bearer {valid_token}'}
)

# Cleanup
try:
    client.revoke_access_token()
    client.revoke_refresh_token()
except Exception as e:
    print(f"Cleanup error: {e}")
```

--------------------------------

### Create or Get Auth Token - Bash

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

Generates JWT-based access and refresh tokens for a community member. It accepts SSO user ID, community member ID, or email as input. Requires a Bearer token for authentication. Responses include tokens, expiry times, and member/community IDs, or detailed error messages for invalid requests.

```bash
curl -X POST https://app.circle.so/api/v1/headless/auth_token \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sso_user_id": "f7b98eb73f7d0d44e4ea52627bbb5a39"
  }'

# Response (200 OK):
{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJjb21tdW5pdHlfaWQiOjEsImNvbW11bml0eV9tZW1iZXJfaWQiOjEsInNzb191c2VyX2lkIjoiZjdiOThlYjczZjdkMGQ0NGU0ZWE1MjYyN2JiYjVhMzkiLCJleHAiOjE3MDg1NDE1MTAsImp0aSI6ImE1MjM2ZmQzLWY4NGItNDcyYy1iNjI2LTcyYTk3YmYwZTcyOSJ9.-MY06GiyXB41dLAx_F4Eu8R4sRxq6QEjy3uLWc4Z6k8",
  "refresh_token": "jaebyVK59l5xxAx1D4pM8H-wYyFA6gMC12RGYZcy44w",
  "access_token_expires_at": "2022-01-01T00:00:00.000Z",
  "refresh_token_expires_at": "2022-01-01T00:00:00.000Z",
  "community_member_id": 1,
  "community_id": 1
}

# Alternative using community member ID:
curl -X POST https://app.circle.so/api/v1/headless/auth_token \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "community_member_id": 12345
  }'

# Alternative using email:
curl -X POST https://app.circle.so/api/v1/headless/auth_token \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

# Error Response (422 Unprocessable Entity):
{
  "success": false,
  "message": "Community member not found. Please provide a valid SSO User ID, community member ID, or email.",
  "error_details": {}
}

# Error Response (403 Forbidden):
{
  "success": false,
  "message": "Your community isn't eligible for headless API access. Please upgrade or contact support",
  "error_details": {}
}
```

--------------------------------

### Revoke Refresh Token API Request

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

This bash snippet demonstrates how to revoke a refresh token using the Circle.so API. It includes the endpoint URL, necessary headers for authorization and content type, and the JSON payload containing the refresh token. It also shows examples of various error responses.

```bash
curl -X POST https://app.circle.so/api/v1/headless/refresh_token/revoke \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "jaebyVK59l5xxAx1D4pM8H-wYyFA6gMC12RGYZcy44w" }'
```

--------------------------------

### Create/Get Auth Token

Source: https://api-headless.circle.so/index

Creates a new authentication token or retrieves an existing one if available.

```APIDOC
## POST /api/v1/headless/auth_token

### Description
Creates or gets an auth token.

### Method
POST

### Endpoint
/api/v1/headless/auth_token

### Response
#### Success Response (200)
```json
{
  "access_token": "string",
  "refresh_token": "string"
}
```
```

--------------------------------

### JavaScript Circle Authentication Client Implementation

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

Provides a comprehensive JavaScript client class for managing the authentication flow with the Circle.so API. It handles token generation, refresh, revocation, and checking token expiry. Dependencies include the `fetch` API.

```javascript
class CircleAuthClient {
  constructor(bearerToken, baseUrl = 'https://app.circle.so') {
    this.bearerToken = bearerToken;
    this.baseUrl = baseUrl;
    this.accessToken = null;
    this.refreshToken = null;
  }

  async authenticate(identifier) {
    // Determine identifier type and create payload
    let payload = {};
    if (identifier.includes('@')) {
      payload.email = identifier;
    } else if (Number.isInteger(identifier)) {
      payload.community_member_id = identifier;
    } else {
      payload.sso_user_id = identifier;
    }

    const response = await fetch(`${this.baseUrl}/api/v1/headless/auth_token`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.bearerToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`Authentication failed: ${error.message}`);
    }

    const data = await response.json();
    this.accessToken = data.access_token;
    this.refreshToken = data.refresh_token;
    this.accessTokenExpiresAt = new Date(data.access_token_expires_at);
    this.refreshTokenExpiresAt = new Date(data.refresh_token_expires_at);

    return data;
  }

  async refreshAccessToken() {
    if (!this.refreshToken) {
      throw new Error('No refresh token available');
    }

    const response = await fetch(`${this.baseUrl}/api/v1/headless/access_token/refresh`, {
      method: 'PATCH',
      headers: {
        'Authorization': `Bearer ${this.bearerToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ refresh_token: this.refreshToken })
    });

    if (!response.ok) {
      const error = await response.json();
      if (response.status === 401) {
        // Refresh token expired, need to re-authenticate
        this.accessToken = null;
        this.refreshToken = null;
        throw new Error('Refresh token expired, re-authentication required');
      }
      throw new Error(`Token refresh failed: ${error.message}`);
    }

    const data = await response.json();
    this.accessToken = data.access_token;
    this.accessTokenExpiresAt = new Date(data.access_token_expires_at);

    return data;
  }

  async revokeAccessToken() {
    if (!this.accessToken) {
      throw new Error('No access token to revoke');
    }

    const response = await fetch(`${this.baseUrl}/api/v1/headless/access_token/revoke`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.bearerToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ access_token: this.accessToken })
    });

    if (!response.ok && response.status !== 204) {
      const error = await response.json();
      throw new Error(`Token revocation failed: ${error.message}`);
    }

    this.accessToken = null;
  }

  async revokeRefreshToken() {
    if (!this.refreshToken) {
      throw new Error('No refresh token to revoke');
    }

    const response = await fetch(`${this.baseUrl}/api/v1/headless/refresh_token/revoke`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.bearerToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ refresh_token: this.refreshToken })
    });

    if (!response.ok && response.status !== 204) {
      const error = await response.json();
      throw new Error(`Refresh token revocation failed: ${error.message}`);
    }

    this.refreshToken = null;
  }

  isAccessTokenExpired() {
    if (!this.accessTokenExpiresAt) return true;
    return new Date() >= this.accessTokenExpiresAt;
  }

  async ensureValidAccessToken() {
    if (!this.accessToken || this.isAccessTokenExpired()) {
      await this.refreshAccessToken();
    }
    return this.accessToken;
  }
}

// Usage example:
const client = new CircleAuthClient('YOUR_BEARER_TOKEN');

// Authenticate with SSO user ID
const authData = await client.authenticate('f7b98eb73f7d0d44e4ea52627bbb5a39');
console.log('Access Token:', authData.access_token);

// Use the access token for API requests
const apiResponse = await fetch('https://app.circle.so/api/v1/some_endpoint', {
  headers: {
    'Authorization': `Bearer ${client.accessToken}`
  }
});

// Automatically refresh when needed
const validToken = await client.ensureValidAccessToken();

// Cleanup: revoke tokens when done
await client.revokeAccessToken();
await client.revokeRefreshToken();

```

--------------------------------

### POST /api/v1/headless/auth_token

Source: https://api-headless.circle.so/api/headless_auth/swagger

This endpoint allows you to create or retrieve an authentication token. It requires an access token in the request body and returns tokens for subsequent API interactions.

```APIDOC
## POST /api/v1/headless/auth_token

### Description
Creates or retrieves an authentication token. This is the primary endpoint for gaining access to the headless API.

### Method
POST

### Endpoint
/api/v1/headless/auth_token

### Parameters
#### Request Body
- **access_token** (string) - Required - The access token to authenticate the request.

### Request Example
```json
{
  "access_token": "YOUR_ACCESS_TOKEN"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The generated access token for API requests.
- **refresh_token** (string) - The refresh token for obtaining new access tokens.
- **access_token_expires_at** (string) - The expiration time of the access token in ISO format.
- **refresh_token_expires_at** (string) - The expiration time of the refresh token in ISO format.
- **community_member_id** (integer) - The ID of the community member.
- **community_id** (integer) - The ID of the community.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJjb21tdW5pdHlfaWQiOjEsImNvbW11bml0eV9tZW1iZXJfaWQiOjEsInNzb191c2VyX2lkIjoiZjdiOThlYjczZjdkMGQ0NGU0ZWE1MjYyN2JiYjVhMzkiLCJleHAiOjE3MDg1NDE1MTAsImp0aSI6ImE1MjM2ZmQzLWY4NGItNDcyYy1iNjI2LTcyYTk3YmYwZTcyOSJ9.-MY06GiyXB41dLAx_F4Eu8R4sRxq6QEjy3uLWc4Z6k8",
  "refresh_token": "jaebyVK59l5xxAx1D4pM8H-wYyFA6gMC12RGYZcy44w",
  "access_token_expires_at": "2022-01-01T00:00:00.000Z",
  "refresh_token_expires_at": "2022-01-01T00:00:00.000Z",
  "community_member_id": 1,
  "community_id": 1
}
```

#### Error Responses
- **401 Unauthorized**: Your account could not be authenticated.
- **403 Forbidden**: Your community isn't eligible for headless API access. Please upgrade or contact support.
- **422 Unprocessable Entity**: Indicates an issue with the request data, such as an invalid access token.
```

--------------------------------

### Circle.so Python Authentication Client

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

A Python class to manage authentication with the Circle.so headless API. It handles obtaining, refreshing, and revoking access and refresh tokens. Dependencies include the 'requests' library for making HTTP calls and 'datetime' for token expiry management. It takes a bearer token for initial authentication and supports authentication via email, community member ID, or SSO user ID.

```python
import requests
from datetime import datetime, timezone
from typing import Optional, Dict, Any

class CircleAuthClient:
    def __init__(self, bearer_token: str, base_url: str = 'https://app.circle.so'):
        self.bearer_token = bearer_token
        self.base_url = base_url
        self.access_token: Optional[str] = None
        self.refresh_token: Optional[str] = None
        self.access_token_expires_at: Optional[datetime] = None
        self.refresh_token_expires_at: Optional[datetime] = None

    def _headers(self) -> Dict[str, str]:
        return {
            'Authorization': f'Bearer {self.bearer_token}',
            'Content-Type': 'application/json'
        }

    def authenticate(self, identifier: Any) -> Dict[str, Any]:
        """
        Authenticate using SSO user ID, community member ID, or email.
        """
        # Determine identifier type
        if isinstance(identifier, str) and '@' in identifier:
            payload = {'email': identifier}
        elif isinstance(identifier, int):
            payload = {'community_member_id': identifier}
        else:
            payload = {'sso_user_id': str(identifier)}

        response = requests.post(
            f'{self.base_url}/api/v1/headless/auth_token',
            headers=self._headers(),
            json=payload
        )

        if not response.ok:
            error_data = response.json()
            raise Exception(f"Authentication failed: {error_data['message']}")

        data = response.json()
        self.access_token = data['access_token']
        self.refresh_token = data['refresh_token']
        self.access_token_expires_at = datetime.fromisoformat(
            data['access_token_expires_at'].replace('Z', '+00:00')
        )
        self.refresh_token_expires_at = datetime.fromisoformat(
            data['refresh_token_expires_at'].replace('Z', '+00:00')
        )

        return data

    def refresh_access_token(self) -> Dict[str, Any]:
        """
        Refresh the access token using the refresh token.
        """
        if not self.refresh_token:
            raise Exception('No refresh token available')

        response = requests.patch(
            f'{self.base_url}/api/v1/headless/access_token/refresh',
            headers=self._headers(),
            json={'refresh_token': self.refresh_token}
        )

        if not response.ok:
            error_data = response.json()
            if response.status_code == 401:
                # Refresh token expired
                self.access_token = None
                self.refresh_token = None
                raise Exception('Refresh token expired, re-authentication required')
            raise Exception(f"Token refresh failed: {error_data['message']}")

        data = response.json()
        self.access_token = data['access_token']
        self.access_token_expires_at = datetime.fromisoformat(
            data['access_token_expires_at'].replace('Z', '+00:00')
        )

        return data

    def revoke_access_token(self) -> None:
        """
        Revoke the current access token.
        """
        if not self.access_token:
            raise Exception('No access token to revoke')

        response = requests.post(
            f'{self.base_url}/api/v1/headless/access_token/revoke',
            headers=self._headers(),
            json={'access_token': self.access_token}
        )

        if not response.ok and response.status_code != 204:
            error_data = response.json()
            raise Exception(f"Token revocation failed: {error_data['message']}")

        self.access_token = None

    def revoke_refresh_token(self) -> None:
        """
        Revoke the current refresh token.
        """
        if not self.refresh_token:
            raise Exception('No refresh token to revoke')

        response = requests.post(
            f'{self.base_url}/api/v1/headless/refresh_token/revoke',
            headers=self._headers(),
            json={'refresh_token': self.refresh_token}
        )

        if not response.ok and response.status_code != 204:
            error_data = response.json()
            raise Exception(f"Refresh token revocation failed: {error_data['message']}")

        self.refresh_token = None

    def is_access_token_expired(self) -> bool:
        """
        Check if the access token is expired.
        """
        if not self.access_token_expires_at:
            return True
        return datetime.now(timezone.utc) >= self.access_token_expires_at

    def ensure_valid_access_token(self) -> str:
        """
        Ensure a valid access token is available, refreshing if necessary.
        """
        if not self.access_token or self.is_access_token_expired():
            self.refresh_access_token()
        return self.access_token

# Usage example
client = CircleAuthClient('YOUR_BEARER_TOKEN')

```

--------------------------------

### Authentication Token API

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

Obtains authentication tokens (access and refresh) for accessing the headless API. Requires Bearer token authentication.

```APIDOC
## POST /api/v1/headless/auth_token

### Description
Obtain authentication tokens (access and refresh) for accessing the headless API. Requires Bearer token authentication.

### Method
POST

### Endpoint
https://app.circle.so/api/v1/headless/auth_token

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **sso_user_id** (string) - Required - The user identifier for single sign-on.

### Request Example
```json
{
  "sso_user_id": "abc123"
}
```

### Response
#### Success Response (200 OK)
Returns authentication tokens and expiration details.

#### Response Example
```json
{
  "access_token": "string (JWT token)",
  "refresh_token": "string (refresh token identifier)",
  "access_token_expires_at": "string (ISO 8601 datetime)",
  "refresh_token_expires_at": "string (ISO 8601 datetime)",
  "community_member_id": 1,
  "community_id": 1
}
```

#### Error Response (401 Unauthorized)
```json
{
  "success": false,
  "message": "Your account could not be authenticated.",
  "error_details": {}
}
```

#### Error Response (422 Unprocessable Entity - Member Not Found)
```json
{
  "success": false,
  "message": "Community member associated with the access token not found.",
  "error_details": {}
}
```
```

--------------------------------

### Community Eligibility Check

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

Checks if the community has the necessary headless API privileges. Access is restricted to eligible communities.

```APIDOC
## Community Eligibility

### Description
The API restricts access to communities with headless API privileges.

### Error Response (403 Forbidden - Ineligible Community)
```json
{
  "success": false,
  "message": "Your community isn't eligible for headless API access. Please upgrade or contact support",
  "error_details": {}
}
```
```

--------------------------------

### Standard Error Response Schema

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

This JSON snippet illustrates the standardized error response schema used across the Circle.so API. It includes a success flag, a human-readable message, and detailed technical error information.

```json
{
  "success": false,
  "message": "string (human-readable error message)",
  "error_details": {
    "message": "string (technical error details)"
  }
}
```

--------------------------------

### POST /api/v1/headless/auth_token

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

Generate authentication tokens for a community member using SSO user ID, community member ID, or email address. Requires Bearer token authentication.

```APIDOC
## POST /api/v1/headless/auth_token

### Description
Generate authentication tokens for a community member using SSO user ID, community member ID, or email address.

### Method
POST

### Endpoint
https://app.circle.so/api/v1/headless/auth_token

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - application/json

#### Request Body
- **sso_user_id** (string) - Required - The SSO user ID of the community member.
- **community_member_id** (integer) - Required - The community member ID.
- **email** (string) - Required - The email address of the community member.

### Request Example
```json
{
  "sso_user_id": "f7b98eb73f7d0d44e4ea52627bbb5a39"
}
```
```json
{
  "community_member_id": 12345
}
```
```json
{
  "email": "user@example.com"
}
```

### Response
#### Success Response (200 OK)
- **access_token** (string) - The generated JWT access token.
- **refresh_token** (string) - The generated JWT refresh token.
- **access_token_expires_at** (string) - The expiration timestamp for the access token.
- **refresh_token_expires_at** (string) - The expiration timestamp for the refresh token.
- **community_member_id** (integer) - The ID of the community member.
- **community_id** (integer) - The ID of the community.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJjb21tdW5pdHlfaWQiOjEsImNvbW11bml0eV9tZW1iZXJfaWQiOjEsInNzb191c2VyX2lkIjoiZjdiOThlYjczZjdkMGQ0NGU0ZWE1MjYyN2JiYjVhMzkiLCJleHAiOjE3MDg1NDE1MTAsImp0aSI6ImE1MjM2ZmQzLWY4NGItNDcyYy1iNjI2LTcyYTk3YmYwZTcyOSJ9.-MY06GiyXB41dLAx_F4Eu8R4sRxq6QEjy3uLWc4Z6k8",
  "refresh_token": "jaebyVK59l5xxAx1D4pM8H-wYyFA6gMC12RGYZcy44w",
  "access_token_expires_at": "2022-01-01T00:00:00.000Z",
  "refresh_token_expires_at": "2022-01-01T00:00:00.000Z",
  "community_member_id": 1,
  "community_id": 1
}
```

#### Error Response (422 Unprocessable Entity)
- **success** (boolean) - False.
- **message** (string) - Error message indicating invalid input.
- **error_details** (object) - Empty object.

#### Error Response Example
```json
{
  "success": false,
  "message": "Community member not found. Please provide a valid SSO User ID, community member ID, or email.",
  "error_details": {}
}
```

#### Error Response (403 Forbidden)
- **success** (boolean) - False.
- **message** (string) - Error message indicating community ineligibility.
- **error_details** (object) - Empty object.

#### Error Response Example
```json
{
  "success": false,
  "message": "Your community isn't eligible for headless API access. Please upgrade or contact support",
  "error_details": {}
}
```
```

--------------------------------

### POST /api/v1/headless/auth_token

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

Authenticates a user and generates access and refresh tokens. The identifier can be an email, community_member_id, or sso_user_id.

```APIDOC
## POST /api/v1/headless/auth_token

### Description
Authenticates a user based on their identifier (email, community_member_id, or sso_user_id) and returns access and refresh tokens.

### Method
POST

### Endpoint
/api/v1/headless/auth_token

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **email** (string) - Optional - The user's email address.
- **community_member_id** (integer) - Optional - The user's community member ID.
- **sso_user_id** (string) - Optional - The user's SSO user ID.

### Request Example
```json
{
  "email": "user@example.com"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The generated access token.
- **refresh_token** (string) - The generated refresh token.
- **access_token_expires_at** (string) - The expiration timestamp for the access token.
- **refresh_token_expires_at** (string) - The expiration timestamp for the refresh token.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_token_expires_at": "2023-10-27T10:00:00Z",
  "refresh_token_expires_at": "2023-11-26T10:00:00Z"
}
```
```

--------------------------------

### Refresh Access Token - Bash

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

Obtains a new access token using a valid refresh token. This endpoint requires the existing refresh token in the request body and Bearer token authentication. Successful responses contain the new access token and its expiry time, while errors indicate issues like a missing or expired refresh token.

```bash
curl -X PATCH https://app.circle.so/api/v1/headless/access_token/refresh \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "jaebyVK59l5xxAx1D4pM8H-wYyFA6gMC12RGYZcy44w"
  }'

# Response (200 OK):
{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJjb21tdW5pdHlfaWQiOjEsImNvbW11bml0eV9tZW1iZXJfaWQiOjEsInNzb191c2VyX2lkIjoiMzI3NjBjNzE3NjcxMTI3ODRlZmQ0Mzc5YjBjNmM2NzAiLCJleHAiOjE3MDg2MDc4MTIsImp0aSI6ImQ1ZjcyY2M1LTE3MWUtNDRlMy1hZWRmLTk0YTNlOGVjM2Q2NCJ9.MLhVBGtmScRCZWbAQ1T-g5wAzwMe4ly1hwgKdv2ie94",
  "access_token_expires_at": "2022-01-01T00:00:00.000Z"
}

# Error Response (404 Not Found):
{
  "success": false,
  "message": "Refresh token not found.",
  "error_details": {}
}

# Error Response (401 Unauthorized):
{
  "success": false,
  "message": "The refresh token is expired. Please generate/get new auth token.",
  "error_details": {}
}

# Error Response (422 Unprocessable Entity):
{
  "success": false,
  "message": "The access token generation failed. Please contact support.",
  "error_details": {
    "message": "JWT::EncodeError"
  }
}
```

--------------------------------

### Authentication Token Response Schema

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

This JSON snippet defines the schema for a successful authentication token response from the Circle.so API. It includes JWT access and refresh tokens, their expiration datetimes, and community identifiers.

```json
{
  "access_token": "string (JWT token)",
  "refresh_token": "string (refresh token identifier)",
  "access_token_expires_at": "string (ISO 8601 datetime)",
  "refresh_token_expires_at": "string (ISO 8601 datetime)",
  "community_member_id": 1,
  "community_id": 1
}
```

--------------------------------

### Community Eligibility Error Response

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

This JSON snippet displays the error response when a community is not eligible for headless API access. It indicates a 403 Forbidden status and provides a message explaining the ineligibility.

```json
{
  "success": false,
  "message": "Your community isn't eligible for headless API access. Please upgrade or contact support",
  "error_details": {}
}
```

--------------------------------

### Refresh Access Token

Source: https://api-headless.circle.so/index

Refreshes an existing access token to extend its validity period.

```APIDOC
## PATCH /api/v1/headless/access_token/refresh

### Description
Refreshes an access token.

### Method
PATCH

### Endpoint
/api/v1/headless/access_token/refresh

### Request Body
```json
{
  "refresh_token": "string"
}
```

### Response
#### Success Response (200)
```json
{
  "access_token": "string"
}
```
```

--------------------------------

### Refreshed Access Token Schema

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

This JSON snippet defines the schema for a response when an access token is successfully refreshed. It provides the new access token and its expiration datetime.

```json
{
  "access_token": "string (JWT token)",
  "access_token_expires_at": "string (ISO 8601 datetime)"
}
```

--------------------------------

### Refresh Access Token API (OpenAPI 3.0.1)

Source: https://api-headless.circle.so/api/headless_auth/swagger

This OpenAPI 3.0.1 definition describes the endpoint for refreshing an access token. It requires a `refresh_token` in the request body and returns a new `access_token` or various error responses (e.g., Not Found, Unauthorized, Unprocessable Entity, Forbidden).

```yaml
openapi: 3.0.1
info:
  title: Headless Auth API
  version: v1
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Authorization header in the format "Bearer AUTH_TOKEN"
  schemas:
    headless_auth_token:
      type: object
      properties:
        access_token:
          type: string
        refresh_token:
          type: string
        access_token_expires_at:
          type: string
        refresh_token_expires_at:
          type: string
        community_member_id:
          type: integer
          minimum: 1
        community_id:
          type: integer
          minimum: 1
    refreshed_access_token:
      type: object
      properties:
        access_token:
          type: string
        access_token_expires_at:
          type: string
    error_response:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        error_details:
          type: object
          nullable: true
paths:
  "/api/v1/headless/access_token/refresh":
    patch:
      summary: Refresh an access token
      tags:
      - Headless
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                success:
                  value:
                    access_token: eyJhbGciOiJIUzI1NiJ9.eyJjb21tdW5pdHlfaWQiOjEsImNvbW11bml0eV9tZW1iZXJfaWQiOjEsInNzb191c2VyX2lkIjoiMzI3NjBjNzE3NjcxMTI3ODRlZmQ0Mzc5YjBjNmM2NzAiLCJleHAiOjE3MDg2MDc4MTIsImp0aSI6ImQ1ZjcyY2M1LTE3MWUtNDRlMy1hZWRmLTk0YTNlOGVjM2Q2NCJ9.MLhVBGtmScRCZWbAQ1T-g5wAzwMe4ly1hwgKdv2ie94
                    access_token_expires_at: '2022-01-01T00:00:00.000Z'
                access_token_not_required:
                  value:
                    access_token: eyJhbGciOiJIUzI1NiJ9.eyJjb21tdW5pdHlfaWQiOjEsImNvbW11bml0eV9tZW1iZXJfaWQiOjEsInNzb191c2VyX2lkIjoiMzI3NjBjNzE3NjcxMTI3ODRlZmQ0Mzc5YjBjNmM2NzAiLCJleHAiOjE3MDg2MDc4MTIsImp0aSI6ImQ1ZjcyY2M1LTE3MWUtNDRlMy1hZWRmLTk0YTNlOGVjM2Q2NCJ9.MLhVBGtmScRCZWbAQ1T-g5wAzwMe4ly1hwgKdv2ie94
                    access_token_expires_at: '2022-01-01T00:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/refreshed_access_token"
        '404':
          description: Not found
          content:
            application/json:
              examples:
                not_found_error:
                  value:
                    success: false
                    message: Refresh token not found.
                    error_details: {}
              schema:
                "$ref": "#/components/schemas/error_response"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                refresh_token_expired_error:
                  value:
                    success: false
                    message: The refresh token is expired. Please generate/get new
                      auth token.
                    error_details: {}
              schema:
                "$ref": "#/components/schemas/error_response"
        '422':
          description: Unprocessable entity
          content:
            application/json:
              examples:
                access_token_generation_failed:
                  value:
                    success: false
                    message: The access token generation failed. Please contact support.
                    error_details:
                      message: JWT::EncodeError
              schema:
                "$ref": "#/components/schemas/error_response"
        '403':
          description: Forbidden
          content:
            application/json:
              examples:
                forbidden:
                  value:
                    success: false
                    message: Your community isn't eligible for headless API access.
                      Please upgrade or contact support
                    error_details: {}
              schema:
                "$ref": "#/components/schemas/error_response"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token:
                  type: string
              required:
              - refresh_token
        required: true
```

--------------------------------

### Refresh Access Token

Source: https://api-headless.circle.so/api/headless_auth/swagger

This endpoint allows you to refresh an existing access token using a valid refresh token. It returns a new access token and its expiration time.

```APIDOC
## PATCH /api/v1/headless/access_token/refresh

### Description
Refreshes an access token using a provided refresh token.

### Method
PATCH

### Endpoint
/api/v1/headless/access_token/refresh

### Parameters
#### Query Parameters
None

#### Request Body
- **refresh_token** (string) - Required - The refresh token to use for obtaining a new access token.

### Request Example
```json
{
    "refresh_token": "your_refresh_token_here"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The newly issued access token.
- **access_token_expires_at** (string) - The expiration timestamp for the new access token.

#### Response Example (Success)
```json
{
    "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJjb21tdW5pdHlfaWQiOjEsImNvbW11bml0eV9tZW1iZXJfaWQiOjEsInNzb191c2VyX2lkIjoiMzI3NjBjNzE3NjcxMTI3ODRlZmQ0Mzc5YjBjNmM2NzAiLCJleHAiOjE3MDg2MDc4MTIsImp0aSI6ImQ1ZjcyY2M1LTE3MWUtNDRlMy1hZWRmLTk0YTNlOGVjM2Q2NCJ9.MLhVBGtmScRCZWbAQ1T-g5wAzwMe4ly1hwgKdv2ie94",
    "access_token_expires_at": "2022-01-01T00:00:00.000Z"
}
```

#### Error Responses
- **404 Not Found**: Refresh token not found.
- **401 Unauthorized**: Refresh token has expired.
- **422 Unprocessable Entity**: Access token generation failed.
- **403 Forbidden**: Community is not eligible for headless API access.
```

--------------------------------

### Revoke Access Token API (OpenAPI 3.0.1)

Source: https://api-headless.circle.so/api/headless_auth/swagger

This OpenAPI 3.0.1 definition describes the endpoint for revoking an access token. It uses a POST request with bearer authentication and returns a 'No Content' response upon successful revocation. It also defines an error response for invalid access tokens.

```yaml
openapi: 3.0.1
info:
  title: Headless Auth API
  version: v1
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Authorization header in the format "Bearer AUTH_TOKEN"
  schemas:
    headless_auth_token:
      type: object
      properties:
        access_token:
          type: string
        refresh_token:
          type: string
        access_token_expires_at:
          type: string
        refresh_token_expires_at:
          type: string
        community_member_id:
          type: integer
          minimum: 1
        community_id:
          type: integer
          minimum: 1
    refreshed_access_token:
      type: object
      properties:
        access_token:
          type: string
        access_token_expires_at:
          type: string
    error_response:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        error_details:
          type: object
          nullable: true
paths:
  "/api/v1/headless/access_token/revoke":
    post:
      summary: Revoke an access token
      tags:
      - Headless
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '204':
          description: No Content
          content:
            application/json:
              examples:
                success: {}
        '422':
          description: Unprocessable entity
          content:
            application/json:
              examples:
                invalid_access_token_error:
                  value:
                    success: false
```

--------------------------------

### PATCH /api/v1/headless/access_token/refresh

Source: https://context7.com/context7/api-headless_circle_so/llms.txt

Refreshes an expired access token using a valid refresh token.

```APIDOC
## PATCH /api/v1/headless/access_token/refresh

### Description
Refreshes an expired access token using a valid refresh token. If the refresh token is also expired or invalid, re-authentication is required.

### Method
PATCH

### Endpoint
/api/v1/headless/access_token/refresh

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **refresh_token** (string) - Required - The user's refresh token.

### Request Example
```json
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The new access token.
- **access_token_expires_at** (string) - The expiration timestamp for the new access token.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_token_expires_at": "2023-10-27T11:00:00Z"
}
```
```