Skip to main content

Authentication

Obtain a Bearer access token from the Auth service, then call Gateway Order APIs with Authorization: Bearer {access_token}.

Prerequisites​

  • EarthLife user credentials (email and password)
  • Active user and organization (inactive user, inactive org, or incomplete org profile can block token issuance)
  • Auth and Gateway hosts below

Auth vs Gateway​

ConcernBase URLPath
Token issuance and refreshhttps://earthlife.sarsatx.com/authPOST /connect/token
Tasking and catalog APIshttps://earthlife.sarsatx.com/gateway/order/...

Always use Content-Type: application/x-www-form-urlencoded for token requests. Use client_id=earthlife-tasking-api.

Password grant​

curl -X POST "https://earthlife.sarsatx.com/auth/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=earthlife-tasking-api" \
  -d "username=user@example.com" \
  -d "password=YOUR_PASSWORD" \
  -d "scope=openid profile email roles offline_access earthlife.orders" \
  -d "culture=en"
FieldRequiredDescription
grant_typeYespassword
client_idYesearthlife-tasking-api
usernameYesAccount email
passwordYesAccount password
scopeRecommendedSpace-separated scopes (see table below)
cultureOptionalLocale hint, e.g. en

Success:

{
  "access_token": "CfDJ8A...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "CfDJ8A...",
  "scope": "openid profile email roles offline_access earthlife.orders"
}

Use the access_token as a Bearer token. Honor expires_in for access-token lifetime (typically ~3600 seconds). With offline_access, refresh tokens may remain valid for up to 365 days.

Refresh grant​

Renew access without sending the password again:

curl -X POST "https://earthlife.sarsatx.com/auth/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=earthlife-tasking-api" \
  -d "refresh_token=CfDJ8A..."

Success: Same shape as the password grant (new access_token, and often a rotated refresh_token). Persist the latest refresh token if the response returns one.

Scopes​

ScopePurpose
openidOpenID Connect identity
profileProfile claims
emailEmail claim
rolesRole information
offline_accessIssues a refresh token for long-lived sessions
earthlife.ordersAccess to EarthLife tasking (Order) APIs

Request all scopes you need in a single space-separated scope value. For API integrations that create and list tasking requests, include at least earthlife.orders and, for refresh, offline_access.

Calling the Gateway​

curl -X GET "https://earthlife.sarsatx.com/gateway/order/Lookup/GetImageTypesList" \
  -H "Authorization: Bearer CfDJ8A..." \
  -H "Accept: application/json"

Required header:

Authorization: Bearer {access_token}

Organization and user gates​

Token issuance can fail even with a correct password when:

  • The user account is inactive
  • The organization is inactive
  • The organization profile is incomplete

These cases typically surface as OAuth errors such as access_denied or invalid_grant. Resolve account or org status with your administrator or Support.

OAuth error responses​

Auth errors return JSON bodies with error and optional error_description.

Invalid credentials or grant:

{
  "error": "invalid_grant",
  "error_description": "invalid_username_or_password"
}

Access denied (policy / account gate):

{
  "error": "access_denied",
  "error_description": "access_denied"
}

Wrong media type: HTTP 415 if Content-Type is not application/x-www-form-urlencoded.

Expired or missing Bearer on Gateway: HTTP 401 on /order/... calls.

See Errors for a broader status-code reference.

Logout and revoke​

There is no separate public “logout” call required for machine-to-machine style clients. To end a session:

  1. Discard access and refresh tokens from your application storage.
  2. Stop using those tokens on subsequent requests.

If you need formal token revocation or session policies for a production deployment, contact Support.

Next steps​