Authentication and setup

Covers the regional base URLs, authentication, data format, rate limits, and status codes for Mindtickle standard REST APIs.

View as Markdown

Mindtickle offers a set of public REST APIs that let you interact programmatically with the platform to automate tasks, integrate with external systems, and manage data efficiently. Built on the OpenAPI Specification (OAS), formerly known as Swagger, these APIs provide a standardized, language-agnostic interface that lets developers integrate with minimal setup.

This page covers the foundational concepts common across Mindtickle’s public REST APIs, including authentication methods, base URLs, rate limiting, and standard status codes. These standards cover APIs such as training content, user management, and Asset Hub. Call AI and Reporting have separate authentication and access guidance.

For any questions or assistance, contact Mindtickle Support.

Base URLs

The base URL for API requests depends on the region where your Mindtickle learning site is hosted and the specific API capability you are accessing.

Standard base URL

Use this URL for most core platform APIs, including user and group management, content, and module completion APIs.

Region	Base URL
Global / Standard	`https://api.mindtickle.com`
US region	`https://api.prod-us.mindtickle.com`

API3 base URL

Use this URL only for the following APIs:

Region	Base URL
Global / Standard	`https://api3.prod.mindtickle.com`
US region	`https://api3.prod-us.mindtickle.com`

URL pattern

Construct your API requests using the pattern [Base URL] + [Endpoint]:

POST https://api.mindtickle.com/services/data/v1.0/content/integration

This example uses the global or standard base URL. Replace it with the base URL for the region where your account is hosted, taken from the tables above.

Authentication

Mindtickle APIs use OAuth 2.0 based authentication with JSON Web Tokens (JWT). To make API calls, you must first generate an access token using your API credentials.

Credentials

You need the following credentials, available in the Mindtickle admin site under Account > Settings > Security and Integrations:

API key
Secret key
Learning site URL, for example example.mindtickle.com

Generate an access token

Exchange your credentials for a Bearer token using the auth endpoint.

Request URL:

POST /services/data/auth_token

Request headers:

Content-Type: application/json

Request body. Replace API_KEY, SECRET_KEY, and LEARNING_SITE_URL with your own credentials:

{
  "api_key": "API_KEY",
  "secret_key": "SECRET_KEY",
  "ls_url": "LEARNING_SITE_URL"
}

Response:

{
  "token": "ACCESS_TOKEN",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Use the access token

Include the generated token in the Authorization header of all subsequent API requests. Replace ACCESS_TOKEN with the token value from the auth response.

Authorization: Bearer ACCESS_TOKEN

Token management

Validity: Tokens are typically valid for 60 minutes (3,600 seconds). Use the expiration information returned by the authentication endpoint.
Best practice: Reuse the token for multiple requests within its validity period. Generate a new token shortly before the returned expiration time or when the API reports that the token has expired.

Data format

Mindtickle APIs use JSON as the standard data format for both request bodies and responses.

Content-Type: Requests should generally include the header Content-Type: application/json.
Character set: UTF-8 is supported.

Rate limits

To ensure stability and fair usage, Mindtickle enforces rate limits on API requests. If you exceed these limits, the API returns a 429 Too Many Requests status code.

Platform defaults

Most standard administrative and content management APIs, such as user and group management, content, and Asset Hub, follow these default limits:

Interval	Limit
Per second	5 requests
Per minute	220 requests
Per hour	3,000 requests

Specialized limits

Some high-volume or data-intensive APIs have limits tailored to their use cases:

API	Limit profile
Seller Copilot and global search	Higher throughput, optimized for real-time interactions: up to 600 requests per minute.
Call AI	Lower limits, because of heavy data payloads: about 10 requests per minute for fetching data, and about 1 request per minute for downloads.

Handling rate limits

When a limit is reached, the API responds with:

Status code: 429 Too Many Requests.
Header: Retry-After, indicating how many seconds to wait before retrying.

For rate-limit errors, use bounded retries with exponential backoff and honor Retry-After when provided. Check the endpoint-specific error description first: some legacy endpoints also use 429 for validation failures, which require correcting the request.

Status codes

Mindtickle APIs use standard HTTP status codes to indicate request outcomes. Where applicable, response bodies also include specific error descriptions to provide further context on failures.

Code	Status	Description
`200`	OK	The HTTP request succeeded. Check the response body for errors or individual task outcomes; an asynchronous operation may still be processing.
`400`	Bad Request	The request was invalid or missing required parameters.
`401`	Unauthorized	Authentication failed. The token is missing, invalid, or expired.
`403`	Forbidden	You do not have permission to access the requested resource.
`404`	Not Found	The requested resource or endpoint does not exist.
`429`	Too Many Requests	Rate limit exceeded. Retry after a delay.
`500`	Internal Server Error	An unexpected error occurred on the server side.