Authentication

IDeaS issues OAuth credentials to integrators. Integrators interact with IDeaS APIs using an OAuth 2.0 client credentials grant flow. This allows for all requests to be authenticated and handles token expiration gracefully. Any OAuth 2.0 compatible HTTP client can be used to interact with IDeaS public APIs

Getting Started

Before diving into the technical implementation details, we recommend refreshing your knowledge of OAuth2 and JWT. The following resources provide thorough explanations and examples to help you understand these protocols:

These links cover the foundational concepts of OAuth2 and JWT, giving you a broader context beyond the specifics of the IDeaS API interaction described in this document.

Prerequisites

To begin using the IDeaS API, ensure you have the following:

Client ID and Client Secret:
- IDeaS will issue a unique client_id and client_secret for your integration.
- Please register as an Integration Partner to request these credentials.
Secure Delivery of Credentials:
- Upon request, your client_id and client_secret will be sent to you through a secure email channel.
- Handle these credentials with care, as they are required for API authentication.

Steps to make an authenticated request

Legend for each step of the sequence diagram:

Client Requests Token. Client initiates the authentication process by sending a request to the OAuth2 server. This request includes the client_id and client_secret as part of the credentials required for authentication.

CURL Example:
```
curl -X POST https://someserver.com/api/oauth2/token
    -H "Content-Type: application/x-www-form-urlencoded"
    -d "grant_type=client_credentials" -d "client_id=***" -d "client_secret=***"
```
OAuth2 Server Creates Token. OAuth2 server validates the credentials and, upon successful verification, generates a JWT (JSON Web Token) with a validity of 60 minutes. This token serves as the client’s authorization to access resources.
Server Responds with JWT Token. OAuth2 server returns the JWT token to the client. This token needs to be included in the client’s future requests to access resources on the resource server.

Response format for this call is the next:
```
{
    "access_token": ***,
    "expires_in": 3600,
    "token_type": "Bearer"
}
```
Note: JWToken is not cached on IDeaS side; a new token is generated with each response. Requestor should cache tokens for up to one-hour (60-minutes), to avoid using the limited resource. Ideally, tokens should be created once per hour. However, it is also possible to request 1 token every 10 minutes, up to 6 tokens per hour.
Client Requests Data from Resource Server. Client makes a request to the resource server for specific resources, including the JWToken in the authorization header of the request. The token acts as proof of authentication.
Authorization Outcome.
- [Auth is passed]: If the token is valid and the client has permission to access the requested resources, the resource server responds with the requested data and an HTTP status code indicating success. Http status code should be from 2** family like 200, 201, 204.
- [Auth is failed]: If the token is invalid, expired, or the client lacks the necessary permissions, the resource server responds with an empty body and an HTTP status code of 403 (Forbidden), indicating the client’s request is denied. If you don’t attach JWToken into Authorization header OAuth server responds with 401 Unauthorized HTTP code.

Limitations

When implementing the IDeaS API authentication and authorization mechanisms, certain limitations should be considered to ensure optimal performance and reliability:

Rate Limits: The API enforces rate limits to control the number of requests per second. If the request volume exceeds the allowed limit, requests will be throttled, and a 429 Rate Limit Exceeded HTTP response will be returned. Clients should implement a backoff and retry a mechanism to handle these responses gracefully.
Token Expiration: Access tokens issued by the authentication system have a limited lifespan. Tokens must be refreshed periodically to maintain access, and clients should handle token expiration logic to avoid interruptions in service.