OAuth2 client-credentials token

POST

/oauth/token

const url = 'https://api.satellitedata.net/oauth/token';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Basic <credentials>',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'cli_9Pw4Zt6Cx2Lb',
    client_secret: 'sdn_Vb7Qx2mN8pL4kR6tY1wZ3cF5hJ9aS0dG7eU2iO4q',
    scope: 'data'
  })
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.satellitedata.net/oauth/token \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=cli_9Pw4Zt6Cx2Lb \
  --data client_secret=sdn_Vb7Qx2mN8pL4kR6tY1wZ3cF5hJ9aS0dG7eU2iO4q \
  --data scope=data

Issues a one-hour JWT bearer token for the OAuth 2.0 client-credentials grant, so Sentinel Hub style clients such as sentinelhub-py and oauthlib can authenticate unchanged. The client id and API key secret go in HTTP Basic or in the form body. Tokens carry the data scope by default. A request with grant_type urn:satellitedata:params:oauth:grant-type:guest and no client authentication returns a one-hour guest token worth 100 units, valid only on tiles and previews; the website requests it for signed-out visitors, and issuance is capped at 3 per IP per day.

Example values only. Keys shown as sdn_... in this operation are illustrations from the design, not real keys. Lean v1 keys are API Gateway keys issued by the service owner and have no sdn_ prefix.

Authorizations

ClientBasic
None

Request Body^required

Form-encoded token request.

application/x-www-form-urlencoded

OAuth 2.0 token request: the client-credentials grant (RFC 6749 section 4.4) or the website guest grant.

object

grant_type

required

Client_credentials for API clients; urn:satellitedata:params:oauth:grant-type:guest for a one-hour, 100-unit guest token with no client authentication.

string

Allowed values: client_credentials urn:satellitedata:params:oauth:grant-type:guest

client_id

Client id, unless sent with HTTP Basic.

string

client_secret

API key secret, unless sent with HTTP Basic.

string

scope

Space-separated scopes; default data.

string

Example

grant_type=client_credentials&client_id=cli_9Pw4Zt6Cx2Lb&client_secret=sdn_Vb7Qx2mN8pL4kR6tY1wZ3cF5hJ9aS0dG7eU2iO4q&scope=data

Responses

200

Token issued.

application/json

OAuth 2.0 token response.

object

access_token

required

JWT access token.

string

token_type

required

Always Bearer.

string

Allowed value: Bearer

expires_in

required

Lifetime in seconds.

integer

scope

Granted scopes.

string

Example

{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjIwMjYtMTAifQ.eyJzdWIiOiJhY2N0XzNGejhLcTFXbjUifQ.c2lnbmF0dXJl",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "data"
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

Cache-Control

string

Caching policy for CloudFront and browsers.

Example

public, max-age=3600, s-maxage=2592000, stale-if-error=604800

400

Unsupported grant type or malformed form.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

unitsEstimated

Units the request would have cost, computed before execution.

number

error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string

Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope

error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string

message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/invalid-token-request",
  "title": "Invalid token request",
  "status": 400,
  "detail": "grant_type must be client_credentials.",
  "instance": "/oauth/token",
  "code": "invalid-token-request",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D",
  "error": "unsupported_grant_type",
  "error_description": "grant_type must be client_credentials"
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

401

Unknown client or wrong secret.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

unitsEstimated

Units the request would have cost, computed before execution.

number

error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string

Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope

error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string

message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/invalid-client",
  "title": "Invalid client",
  "status": 401,
  "detail": "Client authentication failed.",
  "instance": "/oauth/token",
  "code": "invalid-client",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D",
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

WWW-Authenticate

string

Basic challenge.

Example

Basic realm="satellitedata.net"

429

A per-minute, concurrency, monthly or per-IP limit was hit. Retry-After says when to retry.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

unitsEstimated

Units the request would have cost, computed before execution.

number

error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string

Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope

error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string

message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "This key spent 300 of its 300 units in the current minute.",
  "instance": "/v1/process",
  "code": "rate-limited",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D",
  "retryAfter": 17,
  "limits": {
    "unitsPerMinute": 300,
    "unitsSpentThisMinute": 300
  }
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

Retry-After

integer

Seconds to wait before retrying.

Example

RateLimit

string

Remaining units and seconds to reset in the current window (IETF RateLimit header draft).

Example

"units";r=287;t=41

RateLimit-Policy

string

Quota policy of the caller (IETF RateLimit header draft).

Example

"units";q=300;w=60

500

An unexpected server error. No units are charged.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

unitsEstimated

Units the request would have cost, computed before execution.

number

error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string

Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope

error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string

message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/internal",
  "title": "Internal error",
  "status": 500,
  "detail": "The request failed on our side and was logged. No units were charged.",
  "instance": "/v1/process",
  "code": "internal",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D"
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

OAuth2 client-credentials token

Authorizations

Request Bodyrequired

Example

Responses

200

Example

Headers

Example

Example

400

Example

Headers

Example

401

Example

Headers

Example

Example

429

Example

Headers

Example

Example

Example

Example

500

Example

Headers

Example

Request Body^required