---
title: "Check whether a principal may perform an action"
method: POST
path: "/v1/authz/check"
tags: ["Access"]
---

# Check whether a principal may perform an action

`POST /v1/authz/check`

## Request

- Base URL: `https://api.openrelay.inc`
- URL: `https://api.openrelay.inc/v1/authz/check`
- Auth: HTTP bearer

Evaluates one action for a member or key of the organization and returns the decision, the layer that decided it and the deciding policies.

Requires the `policy.read` permission. See [Permissions](https://docs.openrelay.inc/docs/permissions) for the roles and API key permissions that include it.

## Request body

- AccessCheckRequest
  - `action` string, required: An action from the catalog, e.g. compute.create.
  - `endpointId` string: The dedicated endpoint the model is served on.
  - `model` string: The model to check for inference.invoke.
  - `principalId` string, required: A user id or API key id of this organization.
  - `principalType` 'member' | 'api_key', required
  - `sourceIp` string: Evaluate as if the request came from this address. Defaults to yours.

## Response `200`

The decision

- AccessDecision
  - `allow` boolean, required
  - `deniedBy` 'role' | 'key' | 'org_policy' | 'platform'
  - `message` string, required
  - `permission` string, required
  - `policies` AccessDecisionPolicy[], required
    - `id` string, required
    - `source` 'platform' | 'builtin_role' | 'custom_role' | 'key_restriction' | 'guardrail' | 'custom_policy', required

## Other responses

- `400`: The request is invalid
- `401`: Missing or invalid API key
- `403`: The caller is authenticated but may not do this. The caller's role or the API key's permissions do not allow it, or the request targets another organization (FORBIDDEN, or NOT_A_MEMBER for a session); a permission denial also names the action it needed (permission), which kind of policy denied it (deniedBy) and the deciding policy ids (policies). Or the organization is suspended pending review (ORG_SUSPENDED) or has been deleted (ORG_DISABLED). A new API key or a wider scope clears neither of the last two; see [Account and balance refusals](https://docs.openrelay.inc/docs/errors#account-and-balance-refusals). A user session whose email address is not confirmed is refused on every operation (EMAIL_UNVERIFIED); confirm the address from the confirmation email, then sign in again.
- `404`: Resource not found

## Changes

- **2026-10-26** `7fe59d94a9f5`: 4 info
  - added the optional property `requestId` to the response with the `400` status
  - added the optional property `requestId` to the response with the `401` status
  - added the optional property `requestId` to the response with the `403` status
  - added the optional property `requestId` to the response with the `404` status
- **2026-10-22** `551a288b9aa0`: 1 breaking
  - removed the enum value `service_account` of the request property `principalType`
- **2026-10-10** `12b2fcbcc298`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/openrelay/apis/openrelay-api/changes/v1/authz/check/post.md)

---

[API](https://skmtc.dev/openrelay/apis/openrelay-api.md) - [All operations](https://skmtc.dev/openrelay/apis/openrelay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/openrelay/apis/openrelay-api/revisions/7fe59d94a9f5?raw)