insufficient_scope

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
WWW-Authenticate: Bearer error="insufficient_scope", scope="seatime:read"
X-Request-Id: req_01HV9XK...

{
  "type": "https://docs.digitalseaservice.com/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This endpoint requires the seatime:read scope. Granted: profile:read.",
  "instance": "req_01HV9XK..."
}

What it means

The access token is valid and matches a real user, but it wasn’t issued with the scope this endpoint requires. The detail always names the scope the endpoint needs and lists the scopes the token actually carries. The WWW-Authenticate header on the response also carries the needed scope per RFC 6750 §3.1.

Required scopes by endpoint

Endpoint	Required scope
`GET /v1/me`	`profile:read`
`GET /v1/me/sea-time`	`seatime:read`
`GET /v1/me/sea-time/recent`	`seatime:read`
`GET /v1/me/vessels`	`vessels:read`
`GET /v1/webhooks/test`	(any valid token)

What to do

Send the user back through the authorize flow with the missing scope included in the scope parameter. We’ll prompt them to consent to the additional scope — they don’t need to redo the whole connection.

GET /oauth/authorize?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=...
  &scope=profile:read+seatime:read+vessels:read   ← add the missing one
  &state=...
  &code_challenge=...
  &code_challenge_method=S256

Refresh cannot widen scope — there’s no shortcut. Calling /oauth/token with a broader scope than the user originally granted returns invalid_scope. The user has to re-consent.

Get started

Webhooks

Errors

Resources

What it means

Required scopes by endpoint

What to do

​What it means

​Required scopes by endpoint

​What to do

​Related

What it means

Required scopes by endpoint

What to do

Related