Authentication

Prism uses a JWT-based authentication system powered by Amazon Cognito. This guide explains the complete authentication flow, including the prerequisites handled by the AdGem Team and the steps you need to perform to obtain and use access tokens.

Overview

The authentication process involves two phases:

1. Account Setup (performed by AdGem Team): The AdGem Team registers and confirms your user account, then provides you with a refresh_token (a long-lived token).
2. Token Acquisition (performed by you): You exchange the refresh_token for a short-lived JWT access_token, which you include in the Authorization header of all API requests.

Client-side integrations

Run the token exchange on your server and pass the resulting short-lived access_token to your client to make offer requests. Keep the refresh_token server-side — never ship it in client code. See Security for the full credential-handling guidance.

Prerequisites

Before you can authenticate, the AdGem Team must complete the following internal steps for your account:

1. User Registration -- Your user account is registered in the authentication system.
2. User Confirmation -- Your account is confirmed and activated.
3. Refresh Token Generation -- A long-lived refresh_token is generated and shared with you securely.

You do not need to perform these steps yourself. Contact the AdGem Team if you have not received your credentials.

Required Credentials

Credential	Description	Provided By
refresh_token	Your long-lived authentication token (refresh token)	AdGem Team

Step-by-Step Guide

Step 1: Obtain Your Credentials

Contact the AdGem Team to receive your refresh_token. This credential is unique to your application and should be stored only in secure server-side systems to obtain short-lived access tokens.

Credential Security

Treat your refresh_token as a secret. Do not expose it in browser/mobile client code or share it publicly. Call /v1/users/token from your backend, and pass only short-lived access_token values to clients when needed. If you believe your token has been compromised, contact the AdGem Team immediately.

Step 2: Request a JWT Access Token

Make a POST request to the /v1/users/token endpoint with your refresh_token. The endpoint follows the OAuth 2.0 specification (RFC 6749) and requires a form-encoded body:

curl -X POST https://targeted-api.adgem.com/v1/users/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=<your-refresh-token>"

A successful response returns a 201 Created status with your access token:

{
  "message": "Authorized",
  "access_token": "<your-jwt-token>",
  "expires_in": 3600
}

See the Tokens endpoint documentation for full request and response details.

Step 3: Use the JWT Access Token

Include the JWT token in the Authorization header of all subsequent requests:

curl -X POST https://targeted-api.adgem.com/v1/offers \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ offers(player_id: \"user123\") { id name } }"
  }'

Token Expiration

JWT tokens have a limited lifespan. When your token expires, you will receive a 401 Unauthorized response. Simply request a new token using the same process described above.

You can also predict token expiration using the JWT payload's exp claim. This field indicates the expiration time as a Unix timestamp, allowing you to refresh the token proactively before it expires.

Error Handling

HTTP Status	Description
401 Unauthorized	Invalid or expired token. Request a new token.
403 Forbidden	Token is valid but lacks required permissions.
415 Unsupported Media Type	Request Content-Type is not application/x-www-form-urlencoded.
422 Unprocessable Entity	Missing required fields in the request body.

Best Practices

• Store credentials securely: Never expose your refresh_token in client-side code or public repositories.
• Implement token refresh: Monitor for 401 responses and automatically request new access tokens using your refresh_token.
• Proactive refresh: Use the expires_in value or the JWT exp claim to refresh tokens before they expire, avoiding interrupted requests.
• Use HTTPS: Always make requests over HTTPS to protect your credentials and tokens.