---
title: "Authentication and setup"
description: "Covers the regional base URLs, authentication, data format, rate limits, and status codes for Mindtickle standard REST APIs."
contentType: "guide"
url: "https://developer.mindtickle.com/docs/getting-started/authentication-and-setup/"
---

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.

:::note
For Call AI, follow [Call AI authentication](/docs/call-ai/authentication/). For Reporting, follow [Reporting API access](/docs/reporting/use-odata/).
:::

For any questions or assistance, contact [Mindtickle Support](mailto:support@mindtickle.com).

## 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:

- [Asset Hub content APIs](/docs/asset-hub/assets/)
- [Global search API](/docs/search/global-search/run-a-global-search/)
- [Mission learner data migration API](/docs/training/modules/migrate-mission-learner-data/)
- [Module completion API for missions and AI Roleplays](/docs/training/modules/complete-a-mission-or-ai-roleplay/)

| 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]`:

```http
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.

:::note
All API requests must be made over HTTPS. Requests made over plain HTTP or without valid authentication fail.
:::

## 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`

:::note
The secret key is confidential. Use it only to authenticate with the Mindtickle platform and never share it outside your organization.
:::

### Generate an access token

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

Request URL:

```http
POST /services/data/auth_token
```

Request headers:

```text
Content-Type: application/json
```

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

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

Response:

```json
{
  "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.

```text
Authorization: Bearer ACCESS_TOKEN
```

:::note
Match authentication to the API host and region used by the endpoint. A token generated for a different host can cause `No credentials found for given 'iss'`. Some workflows include endpoints on both the standard and API3 hosts, so follow each endpoint's base URL guidance rather than replacing every host with one URL. Do not assume a token works across hosts. If you are unsure which region hosts your account, contact [Mindtickle Support](mailto:support@mindtickle.com).
:::

### 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. |

:::note
Always refer to the documentation for each API to confirm its exact quotas. The limits listed above are subject to change based on fair usage policies.
:::

### 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. |

## Related

- [API overview](/docs/getting-started/api-overview/): The API families these standards apply to.