IDeaS Public API – Security & Authentication

The IDeaS Public API uses OAuth 2.0 Client Credentials to authenticate all requests.

This guide explains how to obtain an access token and use it to securely call IDeaS APIs.

Authentication Overview

Protocol: OAuth 2.0
Grant Type: Client Credentials
Token Format: JWT (Bearer Token)
Token Lifetime: 60 minutes

All API requests must include a valid access token.

Prerequisites

Before integrating with the IDeaS Public API, you must have:

OAuth Credentials

client_id
client_secret

These credentials are issued by IDeaS during onboarding.

Security Note
Treat your client credentials as secrets.
Do not embed them in source control, client-side applications, or logs.

Token Endpoint

Use the OAuth 2.0 token endpoint to request an access token.

POST https://…/oauth2/token

Environment-specific URLs will be provided depending on your integration setup.

Requesting an Access Token

Request Details

Method: POST
Content-Type: application/x-www-form-urlencoded
Grant Type: client_credentials

cURL Example

curl -X POST https://....../api/uis/external_m2m/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"

Token Response

On success, the OAuth server returns a JWT access token.

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

Response Fields

Field	Description
access_token	JWT used to authenticate API request
expires_in	Token validity duration in seconds (3600 = 60 minutes)
token_type	Always Bearer

Using the Access Token

Include the token in the Authorization header for all API requests.

Authorization: Bearer <access_token>

Token Lifecycle & Caching

Tokens are not cached server-side by IDeaS A new token is returned on each successful request Clients are expected to cache tokens locally

Recommended Strategy

Generate one token per hour Reuse the token until expiration Maximum recommended frequency: 6 tokens per hour (one token every 10 minutes)

Excessive token requests may be throttled.

Authorization Outcomes

Authorization Success

Token is valid Client has sufficient permissions

Response:

HTTP 2xx status codes (e.g. 200, 201, 204)
Requested resource returned

Scenario	HTTP Status
Missing Authorization Header	401 Unauthorized
Invalid or expired token	403 Forbidden

Rate Limits

The API enforces rate limits to maintain platform stability.

Exceeding the limit returns:

HTTP 429 - Too Many Requests

Best Practices

Implement retry logic with backoff
Avoid unnecessary token creation
Cache tokens for their full lifetime

Token Expiration Handling

Access tokens expire after 60 minutes Clients must request a new token after expiration Implement renewal logic to prevent service interruption

External References

OAuth 2.0 Overview JSON Web Tokens (JWT) OAuth 2.0 Client Credentials Grant – RFC 6749 §4.4

Next Steps

After authentication, proceed to:

API endpoint documentation
Data models and schemas
Environment-specific testing guidance