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

# Authorization Endpoint

> 🔓 PUBLIC ENDPOINT: Standard OAuth2 authorization endpoint. Validates request parameters and redirects to the consent screen. Supports PKCE for enhanced security. This is the entry point for Authorization Code Flow - compatible with standard OAuth2 clients.

Entry point for the **Authorization Code Flow**. Validates the request and redirects the user's browser to the Timbrix consent screen.

<Note>
  This is a **browser redirect**, not a direct API call. Construct the URL with
  the parameters below and redirect your user to it.
</Note>

<Warning>Rate-limited to **30 requests per minute**.</Warning>

## Query Parameters

| Parameter               | Type   | Required | Description                                                                   |
| ----------------------- | ------ | -------- | ----------------------------------------------------------------------------- |
| `client_id`             | string | Yes      | Your OAuth application client ID                                              |
| `redirect_uri`          | string | Yes      | Redirect URI registered with your application                                 |
| `scope`                 | string | Yes      | Comma-separated list of requested scopes (e.g. `read:user,read:organization`) |
| `state`                 | string | Yes      | Random value for CSRF protection — verify it matches on callback              |
| `response_type`         | string | Yes      | Must be `code`                                                                |
| `code_challenge`        | string | No       | PKCE code challenge — Base64-URL encoded SHA-256 hash of your `code_verifier` |
| `code_challenge_method` | string | No       | `S256` (recommended) or `plain`                                               |

## Example

Construct the URL and redirect your user:

```javascript theme={null}
const params = new URLSearchParams({
  client_id: "app_1234567890abcdef",
  redirect_uri: "https://example.com/oauth/callback",
  scope: "read:user,read:organization",
  state: crypto.randomUUID(), // store this to verify on callback
  response_type: "code",
  // PKCE (recommended)
  code_challenge: "<base64url(sha256(code_verifier))>",
  code_challenge_method: "S256",
})

window.location.href = `https://api.timbrix.com/api/oauth/authorize?${params}`
```

## What happens next

1. The user is shown the Timbrix consent screen with the requested scopes
2. If the user approves, they are redirected to your `redirect_uri` with a `code` and `state` parameter
3. If the user denies, they are redirected with `error=access_denied`
4. Exchange the `code` for tokens using [`POST /oauth/token/exchange`](/api-reference/oauth/exchange)

## Callback example

```
https://example.com/oauth/callback?code=code_abc123xyz&state=<your_state>
```

Always verify the `state` parameter matches the value you generated before proceeding.

## Common Errors

### 400 Bad Request

Invalid `client_id`, `redirect_uri` mismatch, or unsupported `response_type`.

### 302 → consent screen

On success, the user is redirected to the Timbrix consent screen — no JSON response is returned.


## OpenAPI

````yaml GET /oauth/authorize
openapi: 3.1.0
info:
  title: Timbrix API
  description: >-
    REST API with OAuth2 server for managing organizations, members, and
    webhooks
  version: '1.0'
  contact: {}
servers:
  - url: http://sandbox.mintlify.com
    description: Sandbox environment
  - url: http://localhost:3001/api
    description: Local development
security: []
tags:
  - name: organizations
    description: Organization management endpoints
  - name: oauth
    description: OAuth2 authentication and authorization
  - name: webhooks
    description: Webhook configuration and delivery
  - name: users
    description: User information endpoints
  - name: api-keys
    description: API Keys management and validation
paths:
  /oauth/authorize:
    get:
      tags:
        - oauth
      summary: OAuth2 Authorization Endpoint (redirects to consent screen)
      description: >-
        🔓 PUBLIC ENDPOINT: Standard OAuth2 authorization endpoint. Validates
        request parameters and redirects to the consent screen. Supports PKCE
        for enhanced security. This is the entry point for Authorization Code
        Flow - compatible with standard OAuth2 clients.
      operationId: OAuthController_authorize
      parameters:
        - name: client_id
          required: true
          in: query
          description: OAuth application client ID
          schema:
            example: app_abc123...
            type: string
        - name: redirect_uri
          required: true
          in: query
          description: Redirect URI registered with the application
          schema:
            example: https://example.com/oauth/callback
            type: string
        - name: scope
          required: true
          in: query
          description: Comma-separated list of requested scopes
          schema:
            example: read:user,read:organization
            type: string
        - name: state
          required: true
          in: query
          description: >-
            CSRF protection state parameter. Client should generate a random
            value and verify it on callback.
          schema:
            example: random_state_abc123
            type: string
        - name: response_type
          required: true
          in: query
          description: Response type (must be 'code' for Authorization Code Flow)
          schema:
            default: code
            example: code
            type: string
        - name: code_challenge
          required: false
          in: query
          description: >-
            PKCE code challenge (optional, for enhanced security). Base64-URL
            encoded SHA256 hash of code_verifier.
          schema:
            example: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
            type: string
        - name: code_challenge_method
          required: false
          in: query
          description: >-
            PKCE code challenge method. Use 'S256' for SHA256 hashing
            (recommended) or 'plain' for no hashing.
          schema:
            example: S256
            type: string
            enum:
              - S256
              - plain
      responses:
        '302':
          description: >-
            Redirects to consent screen with validated parameters. User will be
            prompted to authorize or deny the application.
        '400':
          description: >-
            Invalid request parameters. Check client_id, redirect_uri, scope,
            state, and response_type.

````