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

# Authentication

> Create, scope and protect the access token every Baato endpoint requires.

Every Baato endpoint requires an access token, passed as the `key` query parameter:

```bash theme={null}
https://api.baato.io/api/v1/search?q=thamel&key=YOUR_BAATO_ACCESS_TOKEN
```

Tokens let us report per-application usage back to you, and protect the endpoints from
unauthorised use.

## Getting a token

<Steps>
  <Step title="Create an account">
    Sign up at [baato.io/signup](https://baato.io/signup) and log in.
  </Step>

  <Step title="Open My Tokens in your dashboard">
    Go to [baato.io/account](https://baato.io/account) and open the **My Tokens** section.
    Baato creates a token named `_default` for you automatically, so you can start making
    requests immediately.
  </Step>

  <Step title="Create additional tokens (optional)">
    Use **Create New Access Token** to add up to three more tokens beyond `_default`. Separate
    tokens per environment — one for local development, one for staging, one for
    production — make usage metrics far easier to read.
  </Step>
</Steps>

## Protecting your token

<Warning>
  A token used from a browser or a mobile app is visible to anyone who opens developer tools
  or inspects the binary. Every web and React Native example in these docs puts the token in
  client-side code for brevity — before you ship, restrict the token to your own domains, or
  proxy Baato requests through your own backend.
</Warning>

<AccordionGroup>
  <Accordion title="Restrict a token to specific domains" icon="shield">
    When you create or edit a token, list your domains in the **allowed origins** field as a
    comma-separated string:

    ```
    example.com,app.example.com
    ```

    Requests carrying that token from any other origin are rejected. This is the right
    control for browser-based applications, where the token cannot be kept secret.
  </Accordion>

  <Accordion title="Keep server-side tokens out of source control" icon="key">
    For the [Python](/libraries/python) and [Go](/libraries/go) clients — and for any
    backend proxy — read the token from the environment rather than hard-coding it:

    <CodeGroup>
      ```python Python theme={null}
      import os
      from baato import BaatoClient

      client = BaatoClient(access_token=os.environ["BAATO_ACCESS_TOKEN"])
      ```

      ```go Go theme={null}
      accessToken := os.Getenv("BAATO_ACCESS_TOKEN")
      baatoMap := baato.Baato(accessToken)
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Rotate a compromised token" icon="rotate">
    Delete the affected token in the dashboard and create a replacement. Requests using the
    deleted token start failing immediately, so deploy the new token first where you can.
  </Accordion>
</AccordionGroup>

## When authentication fails

| Response | Cause                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------------- |
| `401`    | The `key` parameter is missing, malformed, or the token has been deleted.                                            |
| `403`    | The token is valid but the request origin is not in its allowed origins list.                                        |
| `429`    | The token is valid but the account's monthly usage credit is exhausted. See [Pricing and limits](/resources/limits). |

Full details are in the [error reference](/services/errors).

## Next steps

<Columns cols={2}>
  <Card title="Quickstart" icon="rocket" href="/about/quickstart">
    Make your first request and render a map.
  </Card>

  <Card title="API reference" icon="code" href="/services/overview">
    Every endpoint, with an interactive playground.
  </Card>
</Columns>