Check authorization (PDP)

Ask DotID’s policy decision point (PDP) whether a principal in your account is allowed to perform an action on a resource. Use it to enforce DotID’s access model in your own service — the same 10-step evaluation the platform uses.

Endpoint

Method	Path	Purpose
POST	/identity/v1/authorize	Evaluate one request → ALLOW / DENY
POST	/identity/v1/authorize/batch	Evaluate many requests in one call

Base URL: https://api.flexgalaxy.ai (production) or http://api.dev.fgai.test (local dev).

Authentication

This endpoint is authenticated with FGAI-HMAC-SHA256 request signing using an account service-user access key — not a bearer token. Issue a key for your service as described in [CLI & service authentication](https://docs.flexgalaxy.ai/dev/dotid/cli-authentication/), then sign each request with these headers:

Header	Value
Authorization	FGAI-HMAC-SHA256 Credential=<access-key-id>/<date>/<region>/<service>/fgai4_request, SignedHeaders=..., Signature=...
X-FGAI-Date	Request timestamp, yyyyMMddTHHmmssZ (UTC)
X-FGAI-Content-SHA256	Hex SHA-256 of the request body
X-FGAI-Security-Token	Present only for temporary (STS) credentials

See Integrate with AK/SK for the canonical signing detail (canonical request, signing-key derivation, and clock-skew rules).

Decisions are scoped to your key’s account: you can only evaluate principals and resources in the account the access key belongs to. A caller for one account cannot read another account’s grants.

Request

{
  "principal": {
    "account_id": "<account UUID>",
    "user_id": "<user UUID>",
    "user_type": "iam",
    "ic_session": false
  },
  "action": "licensing:Device:Read",
  "resource": "frn:<account-uuid>:licensing:device/dev-98765",
  "context": { "source_ip": "10.0.1.50" }
}

• principal — the identity whose access you are checking (must be in your account). Send ic_session: false for a normal IAM/service user (it is a required boolean — omitting it is rejected). Here user_type is the PDP principal-type discriminator (iam, root, or ic) that selects which evaluator DotID runs — it is not the JWT user_type claim (root / workforce) described in API authentication and JWT validation.

• action — the operation, service:Resource:Verb (e.g. licensing:Device:Read).

• resource — the target as a [FlexGalaxy Resource Name (FRN)](https://docs.flexgalaxy.ai/dev/dotid/frn-format/).

• context — optional attributes evaluated by policy conditions (StringEquals, Bool, …).

Response

{
  "decision": "ALLOW",
  "reason": null,
  "matched_statement": "AllowDeviceRead"
}

• decision — ALLOW or DENY.

• reason — populated on DENY (e.g. EXPLICIT_DENY, IMPLICIT_DENY).

• matched_statement — the policy statement Sid that decided an ALLOW.

The batch endpoint takes { "principal": {…}, "context": {…}, "checks": [ { "action": …, "resource": … }, … ] } — all checks share one principal and optional context — and returns { "results": [ … ] } in the same order.

Behavior

• Fail-closed. A missing or invalid signature returns 401; an authenticated but non-HMAC caller returns 403. Absence of a matching Allow is DENY (IMPLICIT_DENY); a matching Deny always wins (EXPLICIT_DENY).

• Semantics match the platform. This is the same policy engine DotID uses internally; the result you get is the result the platform enforces.

See also: [Hierarchical access](https://docs.flexgalaxy.ai/dev/dotid/hierarchical-access/) for how account/OU/organization policies combine, and [FRN format](https://docs.flexgalaxy.ai/dev/dotid/frn-format/) for addressing resources.