Access Token Request for User Beta

The Access Token Request API is one of the vital component of the token generation workflow, designed to streamline the process of granting access to resources. It facilitates secure communication by triggering a user-driven approval process.

The following illustration depicts the flow and the actions performed by both the Initiator and the Account Holder.

Here's how the process works in detail:

Step 1: Initiating the Request

When the API is invoked, a request for an access token is generated. This triggers a notification to the user, informing them of the pending action required to either approve or reject the request.

Step 2: User Notification

The user is notified through multiple channels to ensure they are aware of the request. Notifications are sent via:

• In-App (Upstox Mobile/Web): A prompt appears within the upstox mobile or web platform.
• WhatsApp: An additional notification is sent to the user's WhatsApp account for convenience.

These notifications provide the necessary details about the request, including the reason and origin, enabling the user to make an informed decision.

Step 3: User Action

The user can either approve or reject the request based on their discretion:

• Approval: If the user approves the request, the access token is securely transmitted to the designated Notifier Webhook Endpoint, which was configured during the app setup process. This ensures that the token reaches the appropriate endpoint for further use.
• Rejection: If the user rejects the request, the token generation process is terminated, and the request is discarded. No token is created or sent.

Note: It is crucial to distinguish this API from the standard token generation API, which is used for generating tokens independently by the Account Holder without external initiation.

Important

Notifier Webhook Endpoint

• The Notifier Webhook Endpoint is a designated URL that must be configured during the app generation process. This endpoint is a POST API hosted by the request initiators where our system will send the access_token. For details on the webhook payload, refer to the Notifier Webhook section for webhook payload.
• For more details and comprehensive setup instructions, see the Notifier Webhook Endpoint section.

Header Parameters

Name	Required	Type	Description
Content-Type	true	string	Indicates the media type of the resource, set as application/json.
Accept	true	string	Defines the content format the client expects, which should be set to application/json.

Path Parameters

Name	Required	Type	Description
client_id	true	string	The API key obtained during the app generation process.

Request Body

{
    "client_secret": "**********"
}

Name	Required	Type	Description
client_secret	true	string	The API secret obtained during the app generation process. This private key remains confidential, known only to the application and the authorization server.

Responses

• 200
• 4XX

---

Response Body

{
    "status": "success",
    "data": {
        "authorization_expiry": "1732226400000",
        "notifier_url": "https://initiator-webhook-endpoint"
    }
}

Name	Type	Description
status	string	A string indicating the outcome of the request. Typically success for successful operations.
data	object	Response data for token request
data.authorization_expiry	string	An expiration time for the access token generation process, starting from the moment a initiator requests the token until the 3:30 AM the following day.
data.notifier_url	string	The Notifier webhook endpoint where the access token is to be sent. The Notifier webhook endpoint must be configured during the app generation process.

{
    "status": "error",
    "errors": [
        {
            "errorCode": "UDAPI1123",
            "message": "Invalid notifier url",
            "propertyPath": null,
            "invalidValue": null,
            "error_code": "UDAPI1123",
            "property_path": null,
            "invalid_value": null
        }
    ]
}

For more details, refer to the Error Response documentation.

Error codes

Error code	Description
UDAPI100069	Check your 'client_id' and 'client_secret'; one or both are incorrect. - Thrown when one of the credentials you've passed to this API is invalid.
UDAPI1123	Invalid notifier url - Thrown when the notifier_url not configured during app generation process.
UDAPI1124	Invalid user type - Thrown when the access token request is not for an individual user.

Notifier Webhook

Once the user approves the initiator's request to generate an access token, the Upstox API will send the following payload to the specified notifier webhook URL:

Response structure:

{
    "client_id": "615b1297-d443-3b39-ba19-1927fbcdddc7",
    "user_id": "******",
    "access_token": "*********",
    "token_type": "Bearer",
    "expires_at": "1731448800000",
    "issued_at": "1731412800000",
    "message_type": "access_token"
}

Name	Type	Description
client_id	string	The API key associated with the app during its generation process, for which the access token has been successfully generated.
user_id	string	Uniquely identifies the user (commonly referred as UCC)
access_token	string	The generated authentication token to be used for all subsequent API requests.
token_type	string	The type of token issued, indicating the authentication scheme to be used, such as Bearer.
expires_at	string	The timestamp indicating when the access token will expire. After this time, the token will no longer be valid for making API requests and a new token may need to be generated.
issued_at	string	The timestamp indicating when the access token was issued. It represents the exact time the token was generated.
message_type	string	The type of webhook response sent to the notifier url. such as access_token

Authorization Expiry

The access token request to obtain the access_token has a defined validity period that expires at 3:30 AM the following day, unless the user approves it sooner.

For example:

• If the initiator requests the token at 8:00 PM on Tuesday, the request will expire at 3:30 AM on Wednesday, at which point it will expire.
• Similarly, if the request is initiated at 2:30 AM on Wednesday, it will still expire at 3:30 AM on the same Wednesday.

Users are encouraged to approve the access token request promptly, keeping the expiration schedule in mind to ensure smooth access and usage.

NOTE

In the Access Token Request, client_id means API Key (not customer UCC) and client_secret means API Secret.

Examples

A comprehensive set of examples is provided to illustrate various use cases and implementation scenarios for this API. To view detailed examples and access sample code, please refer to: API Examples.

Loading...