Single Sign-On · Machine-to-Machine

OAuth 2.0

OAuth 2.0 is used for machine-to-machine API access against the Hygrade REST API, and for first-party web or mobile applications that need delegated access to a user’s Hygrade session.

If you’re looking to let employees sign in to the Hygrade portal, see SAML 2.0 or OpenID Connect. OAuth 2.0 on its own is an authorization framework, not an authentication protocol.

Supported flows

Flow	When to use	Grant type
Authorization Code + PKCE	Web applications, mobile apps, or SPAs acting on behalf of a user.	`authorization_code`
Client Credentials	Server-to-server. Your ERP or middleware calling the Hygrade API as itself.	`client_credentials`
Refresh Token	Rotating a short-lived access token without a fresh user sign-in.	`refresh_token`

The Implicit and Resource Owner Password Credentials grants are intentionally not supported, per OAuth 2.0 Security Best Current Practice.

Endpoints

Authorization endpoint

PRODhttps://order.hygradebusiness.com/oauth/authorize

TESThttps://test.hygradebusiness.com/oauth/authorize

Token endpoint

PRODhttps://order.hygradebusiness.com/oauth/token

TESThttps://test.hygradebusiness.com/oauth/token

Token introspection

PRODhttps://order.hygradebusiness.com/oauth/introspect

TESThttps://test.hygradebusiness.com/oauth/introspect

Token revocation

PRODhttps://order.hygradebusiness.com/oauth/revoke

TESThttps://test.hygradebusiness.com/oauth/revoke

UserInfo (with openid scope)

PRODhttps://order.hygradebusiness.com/oauth/userinfo

TESThttps://test.hygradebusiness.com/oauth/userinfo

JWKS

PRODhttps://order.hygradebusiness.com/oauth/jwks.json

TESThttps://test.hygradebusiness.com/oauth/jwks.json

Scopes

Scope	Grants access to
`openid`	ID token; required for OpenID Connect flows.
`profile`	Name, employee ID, department, cost center.
`email`	Email address and verification status.
`orders:read`	Read own orders and order history.
`orders:write`	Create and cancel orders.
`catalog:read`	Read product catalog, pricing, and inventory.
`users:read`	Read shopper records in your customer account.
`users:write`	Create, update, and deprovision shopper records.
`admin:all`	Full administrative access (customer admins only).

Authorization Code flow (with PKCE)

For interactive applications. PKCE is required for every client, including confidential (server-side) clients.

1. Build the authorization URL

GET /oauth/authorize

GET https://order.hygradebusiness.com/oauth/authorize
    ?response_type=code
    &client_id=hg_live_8f3c92e4a1b04e79
    &redirect_uri=https%3A%2F%2Fapp.acmecorp.com%2Fcallback
    &scope=openid%20profile%20orders%3Aread
    &state=9a1dcf4b
    &code_challenge=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
    &code_challenge_method=S256

2. Exchange the authorization code for a token

POST /oauth/token

curl -X POST https://order.hygradebusiness.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d client_id=hg_live_8f3c92e4a1b04e79 \
  -d client_secret=hg_secret_... \
  -d code=OE82jY3q0s2A8...Jb0 \
  -d redirect_uri=https://app.acmecorp.com/callback \
  -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "hgr_a4f2e8c1d9b34...",
  "scope": "openid profile orders:read",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6..."
}

Client Credentials flow

For headless server-to-server integrations. Hygrade issues a client ID and secret per integration; rotate secrets via the Developer Portal at least every 180 days.

POST /oauth/token

curl -X POST https://order.hygradebusiness.com/oauth/token \
  -u "hg_live_8f3c92e4a1b04e79:hg_secret_..." \
  -d grant_type=client_credentials \
  -d scope="orders:read orders:write catalog:read"

Using the access token

Authenticated request

curl https://api.hygradebusiness.com/v1/orders \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI..."

Refresh tokens

Access tokens live for 60 minutes. Refresh tokens live for 30 days and rotate on each use — the old refresh token is invalidated when a new one is issued.

POST /oauth/token

curl -X POST https://order.hygradebusiness.com/oauth/token \
  -u "hg_live_8f3c92e4a1b04e79:hg_secret_..." \
  -d grant_type=refresh_token \
  -d refresh_token=hgr_a4f2e8c1d9b34...

Access token format

Access tokens are RFC 7519 JWTs signed with RS256. Validate the signature against the JWKS endpoint and enforce the standard claims.

Decoded payload

{
  "iss": "https://order.hygradebusiness.com",
  "sub": "shopper:acme001:jdoe",
  "aud": "api.hygradebusiness.com",
  "exp": 1760731200,
  "iat": 1760727600,
  "jti": "tok_8c3e47a9b1f240d6",
  "scope": "orders:read orders:write catalog:read",
  "client_id": "hg_live_8f3c92e4a1b04e79",
  "cust_id": "ACME001",
  "login": "jdoe"
}

Error responses

Errors follow RFC 6749 §5.2.

400 Bad Request

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired."
}

Common codes

invalid_client — the client ID or secret is wrong, or the client is disabled.
invalid_grant — expired or already-used authorization code or refresh token.
invalid_scope — requested scope is not granted to this client.
unsupported_grant_type — you tried password or implicit (unsupported).

Security requirements

Only HTTPS redirect URIs are accepted. Localhost (http://localhost) is permitted for development.
PKCE is required for every client, including confidential clients.
Client secrets are shown only once at creation time. Rotate via the Developer Portal.
Rate limit: 60 token requests per client per minute. Exceeding returns 429 Too Many Requests.

→

Looking for authentication, not just authorization? Add the openid scope and request an ID token — see OpenID Connect for claim definitions and the discovery document.