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

# OAuth apps

> Create an OAuth 2.0 app that users can authorize for one Biqli workspace.

OAuth apps let your product access the Biqli API on behalf of a user. Every
authorization is bound to one workspace, the approving user, and the exact
scopes requested by your app.

## Create an app

Workspace owners can open **Workspace settings → OAuth Apps** and select
**Create OAuth app**. Register every exact callback URL your product uses.
HTTPS is required, except that HTTP loopback callbacks are accepted for local
development.

The generated client secret is not displayed when the app is created. Open
the app's details menu and select **Regenerate secret** when you are ready to
copy a one-time secret into your server-side secret manager.

Enable **PKCE** only for a public client that cannot safely store a client
secret. Biqli supports the `S256` challenge method.

## Endpoints

| Purpose                    | Method | URL                                  |
| :------------------------- | :----- | :----------------------------------- |
| Authorization              | `GET`  | `https://biq.li/oauth/authorize`     |
| Token exchange and refresh | `POST` | `https://biq.li/api/v1/oauth/token`  |
| Token revocation           | `POST` | `https://biq.li/api/v1/oauth/revoke` |
| Connected identity         | `GET`  | `https://biq.li/api/v1/oauth/me`     |

## Authorization request

Redirect the user to the authorization endpoint with these query parameters:

| Parameter               | Required           | Description                                          |
| :---------------------- | :----------------- | :--------------------------------------------------- |
| `client_id`             | Yes                | Client ID shown on the app details page              |
| `redirect_uri`          | Yes                | An exact registered callback URL                     |
| `response_type`         | Yes                | Must be `code`                                       |
| `state`                 | Yes                | An unpredictable value your app creates and verifies |
| `scope`                 | Yes                | Space-separated least-privilege scopes               |
| `code_challenge`        | For public clients | Base64url-encoded SHA-256 challenge                  |
| `code_challenge_method` | With a challenge   | Must be `S256`                                       |

After approval, Biqli redirects to the callback with a single-use `code` and
the unchanged `state`. Authorization codes expire after five minutes.

## Exchange and refresh tokens

Confidential clients authenticate with `client_id` and `client_secret`.
Public clients omit the secret and send their `code_verifier` during the code
exchange.

```bash theme={null}
curl --request POST \
  --url https://biq.li/api/v1/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'redirect_uri=https://example.com/oauth/callback' \
  --data-urlencode 'code=AUTHORIZATION_CODE'
```

The response contains a short-lived bearer access token and a rotating refresh
token. Store both securely. A refresh token becomes invalid when it is rotated;
reusing the previous value revokes that connection's token family.

## Scopes and workspace access

Request only the permissions your integration needs. Resource scopes use the
same names as workspace API-key permissions, including `links.view`,
`links.create`, and `webhooks.create`. Coarse scopes such as `links.read` and
`webhooks.write` power the dedicated integration endpoints documented on
their own pages; use granular scopes for the standard resource APIs.

Send the access token as a bearer token to supported API endpoints. The token
selects its authorized workspace automatically; do not send internal
`workspaceId` or `workspace_id` fields. Existing workspace role permissions,
plan access, quotas, and resource policies continue to apply.

Webhooks created through an OAuth token belong to that OAuth connection and
are deleted automatically if the connection, OAuth app, or owning workspace
is revoked or removed.

## Revocation

Send an access or refresh token to `POST /api/v1/oauth/revoke`, authenticated
with the app's client credentials. App owners can also remove the OAuth app;
that revokes all of its active connections and deletes its uploaded media.