# Authentication (/docs/authentication)



All Global Fishing Watch API requests must be authenticated with a personal **API access token**, sent as a Bearer token in the `Authorization` header. This page explains how to create a token, how to use it, its limits, and how to resolve authentication errors.

## Get an API access token [#get-an-api-access-token]

1. **Register** for a <a href="https://globalfishingwatch.org/our-apis/tokens/signup" target="_blank">Global Fishing Watch account</a>.
2. **Create** an <a href="https://globalfishingwatch.org/our-apis/tokens" target="_blank">API access token</a> from the token management page.
3. **Agree** to the [terms of use](/docs/license-rate-limits#terms-of-use) and attribute Global Fishing Watch in anything you publish.

Tokens are issued instantly and do not expire, so you normally create one once and reuse it.

<Callout type="warn" title="Keep your token private">
  Your token is specific to you and is your responsibility. Do not share it, publish it, or embed it
  in a public web interface where others could discover it. Using a token that was not issued to you
  violates the [terms of use](/docs/license-rate-limits#terms-of-use).
</Callout>

## Authenticate a request [#authenticate-a-request]

Send your token in the `Authorization` header of every request, prefixed with `Bearer`:

<Tabs items="['cURL', 'Python', 'R', 'JavaScript']">
  <Tab value="cURL">
    ```shell
    curl --location -g --request GET 'https://gateway.api.globalfishingwatch.org/v3/vessels/search?query=7831410&datasets[0]=public-global-vessel-identity:latest' \
      -H "Authorization: Bearer [TOKEN]"
    ```
  </Tab>

  <Tab value="Python">
    ```python
    result = await gfw_client.vessels.search_vessels(
        query="7831410",
        datasets=["public-global-vessel-identity:latest"],
    )
    ```
  </Tab>

  <Tab value="R">
    ```r
    gfw_vessel_info(
      query = "7831410",
      search_type = "search"
    )
    ```
  </Tab>

  <Tab value="JavaScript">
    ```js
    // Make sure to replace [TOKEN] with your API Access Token.
    const res = await fetch(
      'https://gateway.api.globalfishingwatch.org/v3/vessels/search?query=7831410&datasets[0]=public-global-vessel-identity:latest',
      { headers: { Authorization: 'Bearer [TOKEN]' } }
    )
    const data = await res.json()
    ```
  </Tab>
</Tabs>

Replace `[TOKEN]` with your API access token. A successful request returns `200 OK` with the requested data. See the [Quick Start](/docs/quick-start) for a full end-to-end example.

## Token limits [#token-limits]

* **Five tokens per user.** Each account can hold a maximum of five active tokens.
* **Limits are shared across your tokens.** Rate limits are enforced at the user level: requests made through any of your tokens count toward the same daily and monthly totals. Creating extra tokens does not raise your quota. See [Rate Limits](/docs/license-rate-limits#rate-limits) for thresholds and headers.
* **Tokens are not deleted when a rate limit is exceeded.** They stay on your account and work again after the reset period.

## Troubleshooting authentication errors [#troubleshooting-authentication-errors]

Authentication problems return either `401` or `403`. The difference tells you what to fix.

| Code  | Meaning                                                                 | Typical cause                                                  | How to fix                                                                                                                                                               |
| ----- | ----------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401` | **Unauthorized** — the request is not authenticated.                    | Missing, malformed, or invalid token; missing `Bearer` prefix. | Confirm the `Authorization: Bearer [TOKEN]` header is present and the token is copied correctly.                                                                         |
| `403` | **Forbidden** — authenticated, but not allowed to access this resource. | Your token lacks permission for the requested dataset.         | Request access to the dataset, or check the dataset id. Contact [apis@globalfishingwatch.org](mailto:apis@globalfishingwatch.org) if you believe you should have access. |

A `403` from insufficient dataset permissions looks like this:

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "messages": [
    {
      "title": "Forbidden",
      "detail": "Insufficient permissions for public-global-fishing-effort:latest datasets"
    }
  ]
}
```

For the full list of API status codes and error-response formats, see [Errors Codes](/docs/v3/general-api-doc/errors).