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

# OAuth 2.1 Quickstart

> Register an application and get your first access token in five minutes.

HASP supports OAuth 2.1 with PKCE for third-party applications that need to act on behalf of an agent. This is the recommended integration path for any application that will be installed by multiple organizations.

## Step 1 — Register your application

In the developer console (Developer Console → Applications → New Application), enter:

* **Display name** — shown on the consent screen
* **Client type** — choose **Public** (PKCE-only, no client secret) or **Confidential** (client secret issued)
* **Redirect URIs** — the exact callback URLs your app will use

After registering, copy your **Client ID** (`hasp_app_<ulid>`). If you registered a confidential client, save the **Client Secret** (`hasp_cs_live_...`) immediately — it is shown only once.

## Step 2 — Build the authorization URL

Generate a PKCE code verifier and challenge, then redirect the user:

```
https://api.usehasp.com/v1/oauth/authorize
  ?response_type=code
  &client_id=hasp_app_01J...
  &redirect_uri=https://your-app.example.com/callback
  &agent_id=YOUR_AGENT_ID
  &state=<random>
  &code_challenge=<S256 challenge>
  &code_challenge_method=S256
  &authorization_details=[{"type":"hasp.data.read"}]
```

`authorization_details` must be a JSON array, URL-encoded in the actual request (e.g., `%5B%7B%22type%22%3A%22hasp.data.read%22%7D%5D`). The authorize endpoint requires at least one valid RAR grant; omitting `authorization_details` returns `invalid_request`.

The application's detail page in the developer console includes a live URL builder and code snippets in curl, JavaScript, Python, and PHP.

## Step 3 — Handle the callback

After the user approves (or denies), HASP redirects to your `redirect_uri`:

```
https://your-app.example.com/callback
  ?code=<authorization_code>
  &state=<the state you sent>
```

Verify the `state` parameter matches what you sent. Then exchange the code for a token.

## Step 4 — Exchange the code

```bash theme={null}
curl -X POST https://api.usehasp.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=<AUTHORIZATION_CODE>" \
  -d "redirect_uri=https://your-app.example.com/callback" \
  -d "client_id=hasp_app_01J..." \
  -d "client_secret=hasp_cs_live_..." \
  -d "code_verifier=<your PKCE verifier>"
```

Public clients omit `client_secret`.

### Response

```json theme={null}
{
  "access_token": "hasp_agt_live_...",
  "token_type": "Bearer",
  "expires_in": 28800
}
```

## Step 5 — Call the API

Pass the access token as a Bearer token:

```
Authorization: Bearer hasp_agt_live_...
```

## Next steps

* [PKCE in depth](/platform/oauth/pkce) — verifier generation, challenge derivation, and security rationale
* [Consent screen](/platform/oauth/consent-screen) — what the user sees and how to customize it
* [Token introspection](/platform/oauth/introspection) — validate tokens server-side
* [FAQ](/platform/oauth/faq) — scopes, expiry, refresh tokens