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

# Authenticating with the watsonx Orchestrate Developer Edition API

Most watsonx Orchestrate Developer Edition API endpoints require a Bearer token in the `Authorization` header.

The watsonx Orchestrate Developer Edition server uses a two-step token flow. First, post your username and password to `POST /api/v1/auth/token` to get a global user token. Then, post the same credentials to `POST /api/v1/auth/token?tenant_id=<tenant_id>` to exchange it for a tenant-scoped token.

All API calls require the **tenant-scoped token**. Use the global user token only as an intermediate credential to look up your tenant ID.

<Steps>
  <Step title="Get a global user token">
    ```bash BASH theme={null}
    curl -s -X POST http://localhost:4321/api/v1/auth/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "username=<your-username>&password=<your-password>"
    ```

    <Note>
      The `username` and `password` you supply are the credentials you configured when starting the server with `orchestrate server start`, using the `--service-username` and `--service-password` flags.
    </Note>

    Response:

    ```json theme={null}
    {
      "access_token": "<global-jwt-token>",
      "token_type": "bearer"
    }
    ```
  </Step>

  <Step title="Look up your tenant ID">
    Use the global token to list tenants and find your tenant ID:

    ```bash BASH theme={null}
    curl -s http://localhost:4321/api/v1/tenants \
      -H "Authorization: Bearer <global-jwt-token>"
    ```
  </Step>

  <Step title="Get a tenant-scoped token">
    ```bash BASH theme={null}
    curl -s -X POST "http://localhost:4321/api/v1/auth/token?tenant_id=<tenant_id>" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "username=<your-username>&password=<your-password>"
    ```

    Response:

    ```json theme={null}
    {
      "access_token": "<tenant-jwt-token>",
      "token_type": "bearer"
    }
    ```

    Use the `access_token` value from this response as the Bearer token in all subsequent API calls:

    ```bash BASH theme={null}
    curl -s http://localhost:4321/api/v1/agents \
      -H "Authorization: Bearer <tenant-jwt-token>"
    ```
  </Step>
</Steps>