How to Access Instnt API Secure Endpoints

API Authentication Overview

To access the secure endpoints of the Instnt API, you must first authenticate and obtain an access token using the Token Broker API (POST /auth/token). This guide covers the full authentication flow, request and response formats, error handling, and best practices.

🔑 Step 1: Obtain an Access Token

Authenticate by sending a POST request to /auth/token with your account credentials. The API returns a Cognito-backed JWT access token that can be used to call any secure Instnt API endpoint.

Request Structure

Request

POST /auth/token
Content-Type: application/json

{
  "username": "service_user@example.com",
  "password": "your_password"
}
Field Type Required Description
username string Yes Account email address
password string Yes Account password

Successful Response (200 OK)

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyd............",
  "expires_in": 300,
  "token_type": "Bearer",
  "message": "Tokens Issued Successfully",
  "data": {
    "username": "user@email.com",
    "role": "USER_ROLE"
  }
}
Field Type Description
access_token string Cognito-backed JWT used for API calls
token_type string Always Bearer
expires_in integer Access token validity in seconds
message string Human-readable API response message
data object Contains the authenticated username and role

Note: It is the responsibility of the caller to request a new token before the current one expires, as indicated by the expires_in field.

🔗 Step 2: Access Secure API Endpoints

Use the access_token from Step 1 as a Bearer token in the Authorization header. This pattern applies to all Instnt secure API endpoints.

Request

GET /secure/transactions/{transaction_id}
Authorization: Bearer <access_token>

Note: No changes are required to existing secured API endpoints. Only the method for obtaining the token is new.

Reference: Instnt API Documentation

❌ Error Responses

The Token Broker API uses standard HTTP status codes. Error responses include a message field and, when applicable, a detail[] array describing field-level errors.

400 Bad Request

Returned when required fields are missing or contain invalid values.

1. Invalid Username

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "message": "Email 'String' Is Invalid.",
  "detail": [
    {
      "field": "username",
      "issue": "invalid username"
    }
  ]
}

2. Missing Required Field

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "message": "This Field Is Required.",
  "detail": [
    {
      "field": "password",
      "issue": "This Field Is Required."
    }
  ]
}

401 Unauthorized

Returned when credentials are incorrect or a previously issued token has been invalidated.

1. Invalid Credentials

Response

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "message": "Login Failed Due To Invalid Credentials.",
  "detail": [
    {
      "issue": "An error occurred (NotAuthorizedException) when calling the InitiateAuth operation: Incorrect username or password."
    }
  ]
}

2. Invalidated Token (on a Secured API Call)

Response

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "detail": "Token validation failed"
}

🔄 Retry and Recovery Strategy

All clients should implement a retry mechanism to handle token expiration and invalidation gracefully.

Step Action
1 Call the secured API with your current access token.
2 If the API returns 401 Unauthorized, assume the token has expired or been invalidated.
3 Call POST /auth/token to obtain a fresh token.
4 Retry the original request with the new token using exponential backoff (e.g., 100ms, 300ms, 900ms).

Triage Note: This pattern handles natural token expiration, global logout invalidation, and manual session revocation. It is recommended that you configure your client to retry with exponential backoff and a max cap.

⚠️ Global Logout Behavior

The Instnt Logout API performs a global logout for a Cognito user. If the same credentials are used to log in via the Dashboard and to generate tokens via the Token Broker, a Dashboard logout will invalidate all active tokens for that user — including API tokens.

Impact Description
Token invalidation Tokens can become invalid immediately after a Dashboard logout by the same user.
API failures Protected API requests will return 401 Unauthorized until a fresh token is obtained.
Expected behavior This is standard Cognito platform behavior and does not indicate a product incident.

Note: Use dedicated service accounts for API access rather than sharing credentials with Dashboard users. This avoids the global logout side effect entirely.

🔐 Security and Usage Best Practices

Area Recommendation
Service accounts Use dedicated, low-privilege service accounts for API authentication. Rotate credentials periodically.
Token handling Never log access tokens. Store securely (in-memory or secrets store). Cache and reuse until expires_in is reached.
Transport Always use HTTPS for all API calls.
Monitoring Log and alert on repeated 401 responses and token refresh failures to support operational triage.