Admin Authentication

This document outlines the Admin authentication API at Indee. Before delving into this API, we recommend you read through the introduction to Authentication at Indee.

We offer two distinct APIs: one for customers with enterprise-level SSO integration with Indee, and another for non-SSO customers using the Indee authentication system.

API Endpoints	Description
Admin Login	This API allows the admin to log in.
SSO initiation	This API is used to start an SSO login process.
Refresh Token	Creates a new access token when the access token expires.
Log Out	Allows account to logout.

Pre-requisite

Ensure that you have the API key for the appropriate application and scope.

This API allows the admin to log in.

Endpoint

POST v1/admin/auth/login

HTTP Headers

Header	Value
Authorization	Bearer api_key.

Request Body

    {
        "username": "john.doe",
        "password": "abcd@1234",
        "extended_expiry" : False
    }

Parameter	Type	Requirement	Description
`username`	String	Required	Username of the admin user.
`password`	Boolean	Required	Password of the admin user account.
`extended_expiry`	Boolean	Optional	The `extended_expiry` field allows you to configure the duration of the `refresh_token`. Every enterprise can be configured to have a minimum expiration and a maximum expiration of refresh token duration. This parameter allows the client to specify that the token duration has to be maximum as configured for the enterprise.

Response Body

    {
        "status_code": "A0000",
        "status_message": "success",
        "token": <str> #JWT, 
        "refresh_token": <str> #JWT
    }

Field	Type	Description
`status code`	String	Status code provided by Indee.
`status_message`	String	Message body of the status code.
`token`	String	The auth token in OAuth 2.0 nomenclature.
`refresh_token`	String	The refresh token represents its namesake as defined in OAuth 2.0.
.

Error Codes

Indee provides a comprehensive list of Error Codes. To know more, see Common Error and Success Codes.

The SSO login process involves an orchestration between the front end application and the backend Indee servers and the authorization servers of the enterprise. To read more, see Administration Applications (Admin Apps)

SSO Initiation

This API is used to start an SSO login process. The response to the login initiation provides the SSO vendor specific UI that should be launched to start the user journey for SSO login.

Endpoint

    POST v1/admin/auth/sso/initiate

HTTP Headers

Header	Value
Authorization	Bearer api_key.

Request Body

    {
        "username": "john.doe@example.com",
    }

Parameter	Type	Required	Description
`username`	String	Required	The email address of the user.

Response Body

    {
        "state": "lmkbn39KqgTXU8wSf",
        "nonce": "hjklop1XfXArN4tW8",
        "redirect": "https://dev-xcvrqauwz5wfy.us.auth0.com/authorize?client_id=jkljeS0239F38tzRbh7LvMi5w7LHP&response_type=code&scope=openid+profile+email&nonce=hjklop1XfXArN4tW8&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Flogin%2Fsso_callback&state=lmkbn39KqgTXU8wSf",
        "status_code": "A0000",
        "status_message": "success"
    }

Field	Type	Description
`status code`	String	Status code provided by Indee.
`status_message`	String	Message body of the status code.
`state`	String	A random string generated by the SSO provider during the initiation step. It is returned in the initiation API response and also included in the redirect URL after the user completes login. This value must be securely stored by the client and included in the SSO login API request to validate the session and protect against CSRF attacks.
`nonce`	String	A unique, cryptographically random string generated by the SSO provider during the initiation step. It is returned in the initiation API response and must be securely stored by the client. This value is used to associate the client session with the ID token and must be included in the SSO login API request to help prevent replay attacks.

Error Codes

Indee provides a comprehensive list of Error Codes. To know more, see Common Error and Success Codes.

SSO Login

The SSO login API call is the second step in the SSO based authentication process. This API call should be made once the SSO login screen is complete and a callback is made to the front-end application.

Endpoint

    POST v1/admin/auth/sso/login

HTTP Headers

Header	Value
Authorization	Bearer api_key.

Request Body

    {
        "state": "cvbhQlA5FNxRekOw",
        "nonce": "hjkll1p5Fsd9Khrh",
        "email": "enterprisecbs@indee.tv",
        "code": "r0wE1b1h0JynIcxhYAINFlsjsjdXpJ9WOGBUGKujdsk",
        "error": false,
        "error_description": {}
    }

Parameter	Type	Description	Optional/ Required
`state`	String	A random string generated by the SSO provider during the initiation step. This value is returned by our backend in the SSO initiation response. It is later included in the redirect URL after the user completes login via the SSO provider. The client must securely store the original `state` (e.g., in session or memory), validate that it matches the one received in the redirect, and send it in the final SSO login API request to confirm session integrity and prevent CSRF attacks.	Required
`nonce`	String	A unique, cryptographically secure string generated by the SSO provider during the initiation step. This value is returned by our backend in the SSO initiation response and must be securely stored by the client (e.g., in session or memory). After the user completes login with the SSO provider, the client must include the same nonce value in the final SSO login API request to the backend. This ensures that the ID token is tied to the original session and helps prevent replay attacks.	Required
`email`	String	Email ID of the user.	Required
`code`	String	A temporary authorization code issued by the identity provider (e.g., Auth0, Okta) after the user successfully completes login. This code is included in the redirect URL and must be extracted by the client and sent to the backend in the SSO login API request. The backend uses this code to request and exchange for tokens (e.g., access token, ID token) as part of the OAuth 2.0 authorization code flow.	Required
`error`	Boolean	Error code returned by the SSO provider.	Required
`error_description`	String	Error description returned by the SSO provider.	Optional

Response Body

    {
        "status_code": "A0000",
        "status_message": "success",
        "token": <str>, #JWT
        "refresh_token": <str> #JWT
    }

Field	Type	Description
`status code`	String	Status code provided by Indee.
`status_message`	String	Message body of the status code.
`token`	String	The auth token in OAuth 2.0 nomenclature.
`refresh_token`	String	The refresh token represents its namesake as defined in OAuth 2.0.
.

Error Codes

Indee provides a comprehensive list of Error Codes. To know more, see Common Error and Success Codes.

Refresh Token

The access token is valid for 15 mins, however, the refresh token has an expiry time of typically 1 day. The access token should be used in all subsequent API calls to identify the client application.

When the access token expires, the client must call this API to obtain a new access token. The refresh token received in the request object is validated before the generation of new access token. If the validation fails, the A2003(401) unauthorized is sent in the status code and the user is logged out.

Token hotlisting

Under extraordinary circumstances such as a compromised client, refresh token can be hotlisted. Once hotlisted, the refresh and access token will be denied access to make further API calls. Please reach out to support@indee.tv with your hotlisting request.

Endpoint

    POST v1/admin/auth/refresh

HTTP Headers

Header	Value
Authorization	Bearer api_key.

Request Body

    {
        "refresh_token": <str> #JWT
    }

Parameter	Type	Requirement	Description
`refresh_token`	String	Required	The refresh token represents its namesake as defined in OAuth 2.0.

Response Body

    {
        "status_code": "A0000",
        "status_message": "success",
        "token": <str>, #JWT
    }

Field	Type	Description
`status code`	String	Status code provided by Indee.
`status_message`	String	Message body of the status code.
`token`	String	The auth token in OAuth 2.0 nomenclature.

Error Codes

Indee provides a comprehensive list of Error Codes. To know more, see Common Error and Success Codes.

Logout

This API allows the user to log out of Indee account.

Endpoint

    POST v1/admin/auth/logout

HTTP Headers

Header	Value
Authorization	Bearer api_key.

Request Body

    {
        "refresh_token": <str> #JWT
    }

Parameter	Type	Requirement	Description
`refresh_token`	String	Required	The refresh token represents its namesake as defined in OAuth 2.0.

Response Body

    {
        "status_code": "A0000",
        "status_message": "success"
    }

Field	Type	Description
`status code`	String	Status code provided by Indee.
`status_message`	String	Message body of the status code.

Error Codes

Indee provides a comprehensive list of Error Codes. To know more, see Common Error and Success Codes.

Common Error and Success Codes

The API response for authentication APIs follow the common status code format as outlined in the API Status codes.

Success Codes

Indee Status Code	HTTP Status Code
A0000	200

Error Codes

Indee Status Code	HTTP Status Code
A2001	401

Error Response

The error responses for all Auth APIs will follow the model as outlined in Indee Error codes.

    {
        "status_code": "A2002",
        "status_message": "Access Denied"
    }

The HTTP response codes will adhere to Indee Error codes.

Admin Authentication

Pre-requisite

Admin Login

Endpoint

HTTP Headers

Request Body

Response Body

Error Codes

SSO Login

SSO Initiation

Endpoint

HTTP Headers

Request Body

Response Body

Error Codes

SSO Login

Endpoint

HTTP Headers

Request Body

Response Body

Error Codes

Refresh Token

Token hotlisting

Endpoint

HTTP Headers

Request Body

Response Body

Error Codes

Logout

Endpoint

HTTP Headers

Request Body

Response Body

Error Codes

Common Error and Success Codes

Success Codes

Error Codes

Error Response