> ## Documentation Index
> Fetch the complete documentation index at: https://ekso.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Ekso REST API reference — authentication, error handling, versioning, and rate limits.

## Base URL

All API requests are made to your install's URL — whatever public hostname you set during the [first-run wizard](/guide/install/first-run):

```text theme={null}
https://ekso.acme.com/api/
```

Self-host has no concept of a tenant subdomain — every install is its own single addressable identity.

## Authentication

The Ekso API uses **Bearer token** authentication. Include your JWT token in the `Authorization` header of every request:

```text theme={null}
Authorization: Bearer <your-token>
```

Tokens are obtained via the [OAuth 2.0 authorization code flow](/api-reference/introduction#oauth-20) with PKCE.

### OAuth 2.0

Ekso implements OAuth 2.0 with the following endpoints:

| Endpoint            | URL                                       |
| ------------------- | ----------------------------------------- |
| Discovery           | `/.well-known/oauth-authorization-server` |
| Authorization       | `/authorize`                              |
| Token               | `/token`                                  |
| Client registration | `/register`                               |

**Supported grant types:** `authorization_code`, `refresh_token`
**Code challenge method:** S256 (PKCE required)

## Error handling

All error responses share a consistent shape:

```json theme={null}
{
  "kind": "Validation",
  "message": "Human-readable error description",
  "fields": [
    { "field": "email", "code": "required" }
  ]
}
```

| HTTP Status | Kind         | When                                                                     |
| ----------- | ------------ | ------------------------------------------------------------------------ |
| 400         | `Validation` | Field-level validation errors — check the `fields` array                 |
| 403         | `Permission` | Insufficient permissions for this action                                 |
| 422         | `Logic`      | Business rule violation (e.g., item not found, invalid state transition) |
| 500         | `Exception`  | Internal server error                                                    |

The `fields` array is only populated for `Validation` errors.

## Versioning

The API supports versioning via multiple methods:

| Method       | Example                                       |
| ------------ | --------------------------------------------- |
| Query string | `?api-version=1.0`                            |
| URL segment  | `/api/v1.0/...`                               |
| Header       | `x-api-version: 1.0`                          |
| Media type   | `Accept: application/json; x-api-version=1.0` |

If no version is specified, the latest version is used.

## Rate limits

API endpoints are rate-limited to **50 requests per second** per IP address. When the limit is exceeded, the API returns HTTP `429 Too Many Requests`.

## Response format

All responses use **JSON** (`application/json`). Successful responses return HTTP 200 with the data payload directly in the response body.