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

# Authentication

> Authenticate with Connvo using WorkOS-issued bearer tokens and deploy keys.

# Authentication

Connvo relies on WorkOS to authenticate end users and Convex deploy keys to protect privileged endpoints. The OpenAPI specification ships with two security schemes:

* `bearerAuth` — for user-level access with JSON Web Tokens (JWTs) obtained from WorkOS.
* `convexDeploy` — for administrative automation using the `Convex <deploy-key>` header format.

## WorkOS user login flow

1. Redirect users to the WorkOS-hosted login page using your `WORKOS_CLIENT_ID`.
2. After a successful login, WorkOS sends the user back to your `NEXT_PUBLIC_WORKOS_REDIRECT_URI` with an authorization code.
3. Exchange the authorization code for a session token with the WorkOS SDK or REST API.
4. Store the resulting JWT securely (for example in HTTP-only cookies on web clients) and supply it to API calls as `Authorization: Bearer <token>`.

## Obtaining bearer tokens for testing

During development you can generate tokens by signing in through the local Connvo app. Copy the token from the browser dev tools (or use a server-side session exchange) and set it in Mintlify's API playground under the `bearerAuth` security input.

```bash theme={null}
curl https://your-deployment.convex.cloud/api/run/users/getCurrent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <user-token>" \
  -d '{"args": {}, "format": "json"}'
```

## Using deploy keys

Deploy keys unlock admin-only endpoints such as schema migrations or data backfills. Add them to requests as `Authorization: Convex <deploy-key>` and keep them out of client-side code, documentation examples, and public repositories.

## Security best practices

* Never hardcode real tokens into documentation or example requests. Use placeholders like `<user-token>` or `<deploy-key>`.
* Scope deploy keys to the narrowest environment (development, staging, production) required.
* Rotate keys regularly and immediately on suspected compromise.
* Audit logs for unusual API activity, especially around admin endpoints.

With the security schemes defined in the OpenAPI document, Mintlify prompts readers for the correct credentials before executing requests in the playground.