---
title: "Show what a principal can do right now"
method: GET
path: "/v1/authz/effective"
tags: ["Access"]
---

# Show what a principal can do right now

`GET /v1/authz/effective`

## Request

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

Returns the permission ids and actions a member or API key holds right now, and the models it may call, after its restrictions apply.
Without parameters, answers for the caller. Naming a member or key of the organization needs policy.read. The answer is the principal's role intersected with its key restrictions, role conditions and the organization's guardrails.
Network rules are checked against the address of the request you send, not one the named principal would call from.

Checked against the `self.read` permission for the resource it acts on. See [Permissions](https://docs.openrelay.inc/docs/permissions) for the roles and API key permissions that include it.

## Query parameters

- `principalType` 'member' | 'api_key'
- `principalId` string

## Response `200`

Effective access

- EffectiveAccess
  - `actions` string[], required: Every allowed action.
  - `active` boolean: False for a key whose owner left the organization.
  - `allModels` boolean, required
  - `keyKind` 'personal' | 'org' | 'legacy'
  - `models` string[]: Models the principal may call, when not all.
  - `permissions` string[], required: Permission ids fully held, for display.
  - `principalId` string, required
  - `principalType` 'member' | 'api_key', required
  - `restrictions` KeyRestrictions
    - `endpoints` string[]: Dedicated endpoint ids the key may call.
    - `ipRanges` string[]: IPv4 or IPv6 CIDRs the key may be used from, at most 20.
    - `models` string[]: Model ids the key may call. Absent means every model the organization offers.
    - `permissions` string[]: The key's permission ceiling, as permission ids (compute.write). The key can never do more than its owner; absent means the owner's access.
  - `roleId` string
  - `roleName` string

## 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, 2 info
  - removed the enum value `service_account` from the `query` request parameter `principalType`
  - removed the `service` enum value from the `keyKind` response property for the response status `200`
  - removed the `service_account` enum value from the `principalType` response property for the response status `200`
- **2026-10-12** `f5f2b1004ded`: 1 warning
  - added the new `org` enum value to the `keyKind` response property for the response status `200`
- **2026-10-10** `12b2fcbcc298`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/openrelay/apis/openrelay-api/changes/v1/authz/effective/get.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)