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

# Authorize a workspace

> Redirect a user to Biqli and request access to one workspace.

```http theme={null}
GET https://biq.li/oauth/authorize
```

The authorization endpoint signs the user in, displays the requested
permissions, and lets the user choose one accessible workspace.

## Query parameters

| Parameter | Required | Description |
| :- | :- | :- |
| `client_id` | Yes | Public client ID shown on the OAuth application details page. |
| `redirect_uri` | Yes | Exact callback URL registered on the application. |
| `response_type` | Yes | Must be `code`. |
| `state` | Yes | Unpredictable value between 8 and 1,024 characters. |
| `scope` | Yes for self-service apps | Space-separated permissions requested by the integration. |
| `code_challenge` | Public clients | Base64url-encoded SHA-256 digest of the verifier; exactly 43 URL-safe characters. |
| `code_challenge_method` | With a challenge | Must be `S256`. |

```text theme={null}
https://biq.li/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback&response_type=code&state=RANDOM_STATE&scope=workspace.read%20links.view
```

Self-service applications must explicitly request at least one scope. The
requested set must be supported by Biqli and allowed for that client.

## Successful authorization

Biqli redirects to the registered callback URL:

```text theme={null}
https://app.example.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE
```

Verify `state` before using the code. The code expires after five minutes, is
bound to the client, callback URL, user, workspace, scopes, and optional PKCE
challenge, and can be exchanged only once.

## Denied authorization

When the user declines, Biqli redirects with:

| Parameter | Value |
| :- | :- |
| `error` | `access_denied` |
| `error_description` | Short human-readable reason |
| `state` | Original state value |

Do not exchange a code unless the returned state matches the value stored for
the initiating browser session.