Issue Token

This endpoint allows you to generate an authentication token for accessing the Presto API and returns the necessary information to authenticate your API requests.

Overview

The token issue endpoint provides a secure authentication mechanism for accessing the Presto API. Upon validating your credentials, the system generates a new token with your specified name and expiration date, automatically revoking any existing tokens for your account. This token serves as your authentication credential for all subsequent API interactions, ensuring secure and controlled access to the platform's features and resources.

Endpoint Flow

The following diagram illustrates the token issue process:

Endpoint Details

Method: POST URL: /api/institutions/v1/auth/token/issue Purpose: Generate an authentication token for API access

Request Specification

Request Parameters

Parameter	Type	Required	Description
email	string	Yes	The email address associated with your Presto account
password	string	Yes	The password for your Presto account
token_name	string	Yes	A descriptive name for the token to identify its purpose
token_expiration_date	string	Yes	The date when the token will expire (ISO 8601 format: YYYY-MM-DD)

Token Revocation

Issuing a new token will automatically revoke any existing tokens for your account. Ensure that you update all applications using your previous tokens.

Example Request

// Headers:
// Content-Type: application/json

{
  "email": "institution@example.com",
  "password": "your-secure-password",
  "token_name": "Production API Access",
  "token_expiration_date": "2026-05-25"
}

Response Specification

Success Response

200 OK

A successful response contains the authentication token and related information.

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_name": "Production API Access",
    "expiration_date": "2026-05-25T00:00:00+00:00",
    "created_at": "2025-05-25T18:49:51+00:00"
  }
}

Response Fields

Field	Type	Description
token	string	The authentication token to be used in the Authorization header for API requests
token_name	string	The name provided for the token
expiration_date	string	The date when the token will expire (ISO 8601 format)
created_at	string	The timestamp when the token was created (ISO 8601 format)

Error Responses

401 Unauthorized - Authentication issues

{
  "message": "The credentials provided are incorrect"
}

422 Unprocessable Content - Input validation issues

{
  "message": "The token expiration date field must be a valid date.",
  "errors": {
    "token_expiration_date": [
      "The token expiration date field must be a valid date."
    ]
  }
}

422 Unprocessable Content - Missing required fields

{
  "message": "The email field is required. The password field is required.",
  "errors": {
    "email": [
      "The email field is required."
    ],
    "password": [
      "The password field is required."
    ]
  }
}

Error Handling

Common Errors

Error Type	Possible Cause	Resolution
Authentication Error (401)	Incorrect email or password	Verify your email and password are correct
Validation Error (422)	Incorrectly formatted data	Ensure all fields meet the validation requirements (check the 'errors' object in the response)
Validation Error (422)	Missing required fields	Check that all required fields (email, password, token_name, token_expiration_date) are included in your request

Implementation Tips

Best Practices

• Store your authentication token securely
• Include a descriptive token_name that identifies the application or service using the token
• Set a reasonable expiration date based on your security requirements
• Include the token in all API requests using the Authorization header: Authorization: Bearer {token}

Using Your Token

After obtaining an authentication token, include it in the Authorization header of all API requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

For more information about authentication and authorization, see Authorization Overview.