Auth Token API Reference

Overview

The Auth Token API enables clients to exchange their Shen.AI API key for a short-term token. This token can then be used by the end user's browser or device to initialize the SDK and start the measurement process. By using tokens, you enhance security by avoiding direct exposure of your API key to end-users.

This API supports both the redirect flow and the embedded flow:

• Redirect Flow: The SDK is hosted by Shen.AI at https://scan.shen.ai, and the end-user is redirected to it. This flow is commonly used for web applications where the SDK runs in a separate context.
• Embedded Flow: The SDK is embedded within the client's application, whether it's a web or mobile app. This flow allows for seamless integration within your app's environment.

Base URL

All API requests are made to the following base URL:

https://api.shen.ai/v1/

Authentication

Authentication is performed using your Shen.AI API key. Include your API key in the Authorization header as a bearer token:

Authorization: Bearer YOUR_API_KEY

Important: Keep your API key secure and do not expose it in client-side code or public repositories.

Endpoint

POST /auth/token

Description

Generates a short-term token that can be used to initialize the Shen.AI SDK and start measurements.

Request URL

POST https://api.shen.ai/v1/auth/token

Headers

• Content-Type: application/json
• Authorization: Bearer YOUR_API_KEY

Request Parameters

All parameters are optional and should be included in the JSON body of the request.

Example Request

POST /v1/auth/token HTTP/1.1
Host: api.shen.ai
Content-Type: application/json
Authorization: Bearer 123e4567e89b12d3a456426614174000
 
{
  "config_id": 101,
  "max_measurements": 5,
  "token_lifespan": 7200
}

Response Parameters

The response is in JSON format.

Example Successful Response

For Web API Key:

{
  "token": "SHEN-123e4567e89b12d3a456426614174001",
  "expires_in": 7200,
  "redirect_url": "https://scan.shen.ai?token=SHEN-123e4567e89b12d3a456426614174001"
}

For Mobile API Key:

{
  "token": "SHEN-abcdef1234567890abcdef12345678",
  "expires_in": 7200
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure. Error responses include a JSON object with an error field containing details.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Detailed error message."
  }
}

Common Error Codes

Example Error Response

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The 'token_lifespan' must be a positive integer."
  }
}

Examples

Example 1: Requesting a Token with Default Parameters

Request

POST /v1/auth/token HTTP/1.1
Host: api.shen.ai
Content-Type: application/json
Authorization: Bearer abcdef1234567890abcdef1234567890
 
{}

Response (Web API Key)

{
  "token": "SHEN-fedcba0987654321fedcba09876543",
  "expires_in": 3600,
  "redirect_url": "https://scan.shen.ai?token=SHEN-fedcba0987654321fedcba09876543"
}

Example 2: Requesting a Token with Custom Parameters

Request

POST /v1/auth/token HTTP/1.1
Host: api.shen.ai
Content-Type: application/json
Authorization: Bearer 9876543210abcdef9876543210abcdef
 
{
  "config_id": 202,
  "max_measurements": 3,
  "token_lifespan": 86400
}

Response (Mobile API Key)

{
  "token": "SHEN-0987654321abcdef0987654321abcd",
  "expires_in": 86400
}

Example 3: Handling an Exceeded token_lifespan

Request with Exceeding token_lifespan

POST /v1/auth/token HTTP/1.1
Host: api.shen.ai
Content-Type: application/json
Authorization: Bearer abcdef1234567890abcdef1234567890
 
{
  "token_lifespan": 500000  // Exceeds maximum allowed value
}

Response (Note: token_lifespan is truncated to maximum value)

{
  "token": "SHEN-abcdefabcdefabcdefabcdefabcd",
  "expires_in": 259200  // Maximum allowed lifespan in seconds (3 days)
}

Notes and Best Practices

• API Key Security: Never expose your API key in client-side code or public repositories. Always keep it secure on your server.

• Token Usage: The generated token should be securely passed to the client's browser or device. Ensure it is used within its expires_in time frame.

• Token Lifespan Recommendations:

  • Web SDK with Redirect Flow: Use a shorter token_lifespan to enhance security.
  • Mobile SDK with Offline Support: A longer token_lifespan (up to 3 days) is acceptable if the app allows measurements without internet access.

• Measurement Limits: Setting max_measurements helps control the usage of a token. Use it to prevent abuse or overuse.

• Config Management: If you have multiple measurement configurations, specify config_id to select the appropriate one. Otherwise, the default or license-assigned configuration will be used.

• Separate API Keys for Web and Mobile:

  • Web API Key: Returns redirect_url in the response. Only valid for use with the Web SDK.
  • Mobile API Key: Does not return redirect_url. Only valid for use with the Mobile SDK.

Frequently Asked Questions (FAQ)

Q: What happens if I provide a token_lifespan that exceeds the maximum allowed value?

A: The token_lifespan will be automatically set to the maximum allowed value of 259200 seconds (3 days).

Q: Can I use the same API key for both Web and Mobile SDKs?

A: No. For security reasons, Web and Mobile API keys are separate. Each is restricted to its respective SDK.

Q: What should I do if I receive an INVALID_REQUEST error?

A: Check the error message for details about which parameter is invalid or missing, and adjust your request accordingly.

Changelog

• v1.0 - Initial release of the API.