Authentication & Login

All API Broker APIs use Bearer (JWT) token-based authentication managed through AWS Cognito. Every API request must include a valid token in the authorization header. Without it, the API returns 401 Unauthorized.

Authentication Process

Step 1 — Login

The first step is to obtain a token by calling the login endpoint with the credentials assigned by API Broker.

Endpoint

POST /api/auth/login

Request body:

{
  "username": "your_username",
  "password": "your_password"
}

Response:

{
  "AccessToken": "eyJraWQiOiJ...",
  "ExpiresIn": 3600,
  "TokenType": "Bearer",
  "RefreshToken": "eyJjdHkiOiJ...",
  "IdToken": "eyJraWQiOiJ..."
}

Save both the AccessToken and the RefreshToken. The first is used in every request; the second allows you to renew the session when the AccessToken expires without prompting for a password again.

Step 2 — Use the token in every request

All API endpoints require the AccessToken in the Authorization header:
Authorization: Bearer {AccessToken}

Example:

curl -X GET https://apibroker.prd-adcap.com/api/accounts/persons?person_id=F-9686d35b \
  -H "Authorization: Bearer eyJraWQiOiJ..."

In code:

const response = await fetch('https://apibroker.prd-adcap.com/api/accounts/persons', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

Step 3 — Refresh the token

The AccessToken expires after 3600 seconds (1 hour). When that happens, the API returns 401 Unauthorized. To avoid interrupting operations, there are two options:

Option A — Log in again (simpler)

Call POST /api/login again with your username and password to obtain a fresh AccessToken.

Option B — Use the Refresh Token (recommended for production integrations)

The RefreshToken has a longer lifespan and allows you to obtain a new AccessToken without exposing credentials on every request. This is ideal for continuously running systems.

Credentials

Access credentials (username and password) are assigned by the API Broker team during the integration process, at the Staging Credentials stage and later at the Production Credentials stage.

If you need credentials or access resets, contact your account manager or write to [email protected].

Security best practices:

• Never include credentials directly in source code.
• Store them as environment variables or in a secrets manager.
• Do not share them across teams without authorization.
• Rotate them periodically or at any sign of compromise.

Authentication-related response codes

Recommended Implementation

For production integrations, the recommended approach is:

1. On application startup, perform the login and store the AccessToken and RefreshToken in memory (never in public storage).
2. On every request, attach the AccessToken in the Authorization header.
3. On receiving a 401, attempt to automatically refresh the token using the RefreshToken before propagating the error to the user.
4. If the refresh also fails, initiate a new login with credentials.

This ensures a seamless experience with no interruptions due to session expiration.

Key Points to Remember

1. Every request needs Authorization: Bearer {AccessToken} — no exceptions.
2. The token expires in 1 hour. Implement automatic renewal in production.
3. Credentials are environment-specific. STG and PRD have separate users.
4. 401 = expired or missing token. 403 = insufficient permissions. These are different errors.
5. Never hardcode credentials in source code or repositories.
6. Credentials are assigned by API Broker during the integration process. They are not self-managed.