Authentication
Create an API access token, authenticate your requests, and troubleshoot 401/403 errors.
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
- Register for a Global Fishing Watch account.
- Create an API access token from the token management page.
- Agree to the 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.
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.
Authenticate a request
Send your token in the Authorization header of every request, prefixed with Bearer:
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]"result = await gfw_client.vessels.search_vessels(
query="7831410",
datasets=["public-global-vessel-identity:latest"],
)gfw_vessel_info(
query = "7831410",
search_type = "search"
)// 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()Replace [TOKEN] with your API access token. A successful request returns 200 OK with the requested data. See the Quick Start for a full end-to-end example.
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 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
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 [email protected] if you believe you should have access. |
A 403 from insufficient dataset permissions looks like this:
{
"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.