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

# API overview

> Understand the Ekso REST API — base URL, OAuth 2.0 authentication, error handling, and response conventions.

The Ekso API is a REST API that lets you manage items, boards, containers, time entries, and every other resource in your tenant programmatically. This page covers the architecture — for a hands-on walkthrough, see the [Quickstart](/guide/api/quickstart).

## Base URL

All API requests target your install's URL — the `PublicUrl` you set during the `/startup` wizard:

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

Replace `ekso.acme.com` with your install's hostname. Every endpoint described in the [API reference](/api-reference/introduction) is relative to this base.

## Authentication

Ekso uses **OAuth 2.0 with PKCE** (Proof Key for Code Exchange). PKCE is the recommended flow for public clients — it protects against authorization code interception without requiring a client secret.

### Discovery

Fetch the OAuth metadata from your install's well-known endpoint:

```bash theme={null}
curl https://ekso.acme.com/.well-known/oauth-authorization-server
```

This returns the authorization, token, and registration endpoints you need for the flow.

### Flow summary

1. **Generate a code verifier and challenge** — create a random string (verifier) and its SHA-256 hash (challenge)
2. **Redirect to the authorization endpoint** — include the code challenge, a redirect URI, and requested scopes
3. **User approves** — Ekso redirects back to your app with an authorization code
4. **Exchange code for tokens** — POST the authorization code and code verifier to the token endpoint
5. **Use the access token** — include it in the `Authorization` header of every API request

See the full [OAuth 2.0 details](/api-reference/introduction#oauth-20) in the API reference.

### Using the token

Add the access token to every request as a Bearer token:

```bash theme={null}
curl https://ekso.acme.com/api/board \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Error format

All errors follow a consistent JSON structure:

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

### Error kinds

| Status | Kind         | Meaning                                                                     |
| ------ | ------------ | --------------------------------------------------------------------------- |
| 400    | `Validation` | One or more fields failed validation — check the `fields` array for details |
| 403    | `Permission` | The authenticated user lacks the required permissions                       |
| 422    | `Logic`      | A business rule was violated (e.g., closing an already-closed cycle)        |
| 500    | `Exception`  | An unexpected server error — contact support if this persists               |

The `fields` array is only present on `Validation` errors. Each entry identifies the field name and a machine-readable error code.

## Response conventions

* **Lists** return JSON arrays directly (e.g., `GET /api/board` returns `[{...}, {...}]`)
* **Single resources** return a JSON object (e.g., `GET /api/board/{id}` returns `{...}`)
* **Creates and updates** return the full resource after the operation
* **Deletes** return `204 No Content` on success
* All response bodies use **camelCase** property names

## Token lifetimes and limits

When building integrations, keep these OAuth token lifetimes and client limits in mind:

| Setting                      | Value                                      |
| ---------------------------- | ------------------------------------------ |
| Access token lifetime        | 15 minutes                                 |
| Authorization code lifetime  | 5 minutes                                  |
| Refresh token lifetime       | 30 days                                    |
| PKCE code challenge method   | S256                                       |
| Max OAuth clients per tenant | 50                                         |
| Client staleness threshold   | 90 days (unused clients may be cleaned up) |

<Note>
  Access tokens expire after 15 minutes. Your integration should use the refresh token to obtain a new access token before the current one expires. Refresh tokens are valid for 30 days — if a refresh token expires, the user must re-authorize.
</Note>

## Next steps

<Columns cols={3}>
  <Card title="Quickstart" icon="rocket" href="/guide/api/quickstart">
    Authenticate and make your first API call in minutes.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Explore the full REST API with all endpoints and schemas.
  </Card>

  <Card title="MCP tools" icon="robot" href="/mcp-tools/introduction">
    Connect AI agents directly to Ekso — no REST calls needed.
  </Card>
</Columns>