OAuth 2.0 Authentication

[!INFO] Quick Summary

The a55 API uses OAuth 2.0 Client Credentials flow via AWS Cognito. You'll exchange your credentials for a JWT access token, then include it in all API requests.

---

Authentication Flow

sequenceDiagram
    autonumber
    participant P as Partner Backend
    participant C as AWS Cognito
    participant A as a55 API
    
    Note over P,A: Authentication Flow
    
    P->>+C: POST /oauth2/token
    Note right of P: client_id + client_secret
    C-->>-P: access_token (JWT)
    
    Note over P,A: API Requests
    
    P->>+A: GET /v1/wallets
    Note right of P: Authorization Bearer token
    A-->>-P: 200 OK + data
    
    Note over P,A: Token Refresh
    
    P->>+C: POST /oauth2/token refresh
    C-->>-P: new access_token

🔍

Click here to view full diagram with zoom

Step 1: Request Access Token

Request Body

import requests

def get_access_token():
    url = "https://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token"
    
    payload = {
        "grant_type": "client_credentials",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET"
    }
    
    headers = {
        "Content-Type": "application/x-www-form-urlencoded"
    }
    
    response = requests.post(url, data=payload, headers=headers)
    return response.json()["access_token"]

curl -X POST \
  https://smart-capital.auth.us-east-1.amazoncognito.com/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"

Step 2: Token Response

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

Step 3: Use Token in API Requests

Include the token in the Authorization header:

def call_api(access_token, endpoint):
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    response = requests.get(
        f"https://core-manager.a55.tech/api/v1/{endpoint}",
        headers=headers
    )
    return response.json()

curl -X GET \
  https://core-manager.a55.tech/api/v1/wallets \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Token Management Best Practices

[!WARNING] Security Notice The client_secret must be stored securely on your backend. Never include it in client-side code, mobile apps, or public repositories.

Need Credentials?

[!TIP] Contact Our Team To request your OAuth2 credentials, email [email protected] with:

• Company Name
• Technical Contact
• Expected use case

Next Steps

1. Environment — Configure sandbox and production endpoints
2. Integration Overview — Choose your integration method