Authentication

Quick Reference

WhatOAuth 2.0 authentication via AWS Cognito

WhyGet a Bearer token to authorize every API request — with production-ready caching

Reading Time5 min

DifficultyBeginner

PrerequisitesIntroduction

Why token-based auth matters

Without proper auth management	With A55 best practices
New token request on every API call — slow and rate-limited	Cache and reuse the token for up to 1 hour
Credentials scattered in code, configs, and logs	Single secrets-manager entry, zero exposure
Expired tokens cause silent 401 failures in production	Proactive refresh before expiry keeps uptime at 100%
Debugging auth issues wastes integration hours	One flow, one endpoint, one token format — JWT everywhere

How it works

Exchange client_id + client_secret for a JWT access_token (valid for 1 hour). Send that token as Authorization: Bearer <token> on every API call. Refresh before it expires.

---

Authentication flow

---

Step 1 — Request an access token

Setting	Value
Endpoint	https://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token
Method	POST
Content-Type	application/x-www-form-urlencoded

Field	Value
grant_type	client_credentials
client_id	Your OAuth 2.0 client ID
client_secret	Your OAuth 2.0 client secret

cURL

curl -s -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"

Python

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)
    response.raise_for_status()
    return response.json()["access_token"]

JavaScript

async function getAccessToken() {
  const response = await fetch(
    "https://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token",
    {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        grant_type: "client_credentials",
        client_id: "YOUR_CLIENT_ID",
        client_secret: "YOUR_CLIENT_SECRET",
      }),
    }
  );
  const data = await response.json();
  return data.access_token;
}

---

Step 2 — Understand the token response

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

Field	Type	Description
access_token	string	JWT used as the Bearer token in every API request
expires_in	integer	Token lifetime in seconds (default 3600 = 1 hour)
token_type	string	Always Bearer

Decode the JWT

Paste your access_token into jwt.io during development to inspect claims, scopes, and expiry. Never do this with production tokens on untrusted sites.

---

Step 3 — Call the API

Send Authorization: Bearer <access_token> on every request.

cURL

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

Python

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

JavaScript

async function callApi(accessToken, method, endpoint, payload) {
  const response = await fetch(
    `https://core-manager.a55.tech/api/v1/${endpoint}`,
    {
      method,
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json",
      },
      body: payload ? JSON.stringify(payload) : undefined,
    }
  );
  return response.json();
}

---

Step 4 — Cache and refresh tokens

Tokens last 1 hour. Request a new one before it expires — never wait for a 401.

Python

import time
import requests

class A55Client:
    AUTH_URL = "https://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token"
    API_BASE = "https://core-manager.a55.tech/api/v1"
    REFRESH_MARGIN = 300  # refresh 5 min before expiry

    def __init__(self, client_id: str, client_secret: str):
        self._client_id = client_id
        self._client_secret = client_secret
        self._token = None
        self._token_expiry = 0

    def _refresh_token(self):
        resp = requests.post(self.AUTH_URL, data={
            "grant_type": "client_credentials",
            "client_id": self._client_id,
            "client_secret": self._client_secret,
        }, headers={"Content-Type": "application/x-www-form-urlencoded"})
        resp.raise_for_status()
        data = resp.json()
        self._token = data["access_token"]
        self._token_expiry = time.time() + data["expires_in"] - self.REFRESH_MARGIN

    @property
    def token(self) -> str:
        if not self._token or time.time() >= self._token_expiry:
            self._refresh_token()
        return self._token

    def request(self, method: str, endpoint: str, **kwargs):
        headers = {
            "Authorization": f"Bearer {self.token}",
            "Content-Type": "application/json",
        }
        resp = requests.request(method, f"{self.API_BASE}/{endpoint}", headers=headers, **kwargs)
        resp.raise_for_status()
        return resp.json()

client = A55Client("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
wallets = client.request("GET", "wallets")
print(wallets)

JavaScript

class A55Client {
  #token = null;
  #tokenExpiry = 0;
  static AUTH_URL = "https://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token";
  static API_BASE = "https://core-manager.a55.tech/api/v1";
  static REFRESH_MARGIN = 300_000; // 5 min in ms

  constructor(clientId, clientSecret) {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
  }

  async #refreshToken() {
    const resp = await fetch(A55Client.AUTH_URL, {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        grant_type: "client_credentials",
        client_id: this.clientId,
        client_secret: this.clientSecret,
      }),
    });
    const data = await resp.json();
    this.#token = data.access_token;
    this.#tokenExpiry = Date.now() + data.expires_in * 1000 - A55Client.REFRESH_MARGIN;
  }

  async getToken() {
    if (!this.#token || Date.now() >= this.#tokenExpiry) {
      await this.#refreshToken();
    }
    return this.#token;
  }

  async request(method, endpoint, payload) {
    const token = await this.getToken();
    const resp = await fetch(`${A55Client.API_BASE}/${endpoint}`, {
      method,
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: payload ? JSON.stringify(payload) : undefined,
    });
    return resp.json();
  }
}

const client = new A55Client("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
const wallets = await client.request("GET", "wallets");
console.log(wallets);

---

Token management checklist

Practice	Why
Cache tokens for up to 55 minutes	Avoids unnecessary Cognito calls and rate limits
Refresh 5 minutes before expires_in	Prevents 401 errors during API calls
Store client_secret in a secrets manager	Env vars leak in logs; secrets managers do not
Never log tokens or secrets	A leaked token grants full API access for 1 hour
Use HTTPS everywhere	Tokens in plaintext HTTP can be intercepted
Rotate secrets periodically	Limits blast radius if a credential is compromised

Client secret is a password

Treat client_secret like a database password: backend-only storage, never in browsers, mobile apps, CI logs, or public repositories. If compromised, email tech.services@a55.tech immediately for rotation.

---

Error responses

HTTP status	Meaning	What to do
401 Unauthorized	Token expired or invalid	Refresh the token and retry
400 Bad Request	Malformed auth request	Check grant_type, client_id, client_secret
429 Too Many Requests	Rate limit hit on Cognito	Implement exponential backoff; cache your tokens

---

Request credentials

Email tech.services@a55.tech with your company name, technical contact, and expected use case to receive client_id and client_secret for sandbox and production.

Environment →Sandbox vs production — same URL, different credentials.Create your first charge →Use your token to process a payment.Integration Overview →Compare H2H, SDK, and Checkout Page before you build.