canonical: https://jentic.com/apis/authress.io/authress

# Authress

Jentic publishes the only available OpenAPI specification for Authress, keeping it validated and agent-ready. Authress is a fine-grained authorization service that handles user permissions, role-based access control, and multi-tenant identity for SaaS applications. The API exposes 75 endpoints covering users, groups, roles, access records, resource configurations, invites, service clients, tenants, and OAuth connections, all addressable by URI so authorization decisions can target individual records or entire resource hierarchies. A single GET on `/v1/users/{userId}/resources/{resourceUri}/permissions/{permission}` answers 'can this user perform this action?' in one call.

## For AI agents

Verify whether a user has a specific permission on a resource, grant access by creating access records, and manage roles, groups, tenants, and service clients for a multi-tenant SaaS app.

## Scope

Does not handle user authentication, password storage, or MFA enrollment - use for authorization, RBAC, and access record management only.

## Capabilities

- Verify a user's permission on a resource URI with GET `/v1/users/{userId}/resources/{resourceUri}/permissions/{permission}`
- Grant or revoke access by creating, updating, and deleting access records under `/v1/records`
- Manage roles and their permission sets via the `/v1/roles` endpoints
- Organize users into groups and assign roles to a group via `/v1/groups`
- Invite users into a tenant with POST `/v1/invites` and accept invites by token
- Provision service clients for machine-to-machine access via `/v1/clients`
- Configure resource hierarchies and inherited permissions via `/v1/resources/{resourceUri}`

## Use cases

### Per-request permission check

Replace bespoke RBAC code with a single Authress call. When a request reaches your API, call GET `/v1/users/{userId}/resources/{resourceUri}/permissions/{permission}` - Authress returns 200 if the user is allowed and 403 if not, taking inheritance, group membership, and role assignments into account. This lets services stay stateless about authorization and removes the need to keep a permissions table in sync across microservices.

Example prompt: Send GET `/v1/users/user_abc/resources/projects`%2Fproj_42/permissions/read and treat a 200 response as authorized

### Multi-tenant SaaS access control

Model a multi-tenant SaaS where each customer organization needs its own admins, members, and resource isolation. Create a tenant per customer via `/v1/tenants`, define roles like admin, editor, and viewer in `/v1/roles`, and bind them to users with access records that scope by tenant URI. Cross-tenant data leakage becomes a structural impossibility because every permission check carries the tenant URI in the resource path.

Example prompt: Create a tenant, define an admin role, then POST `/v1/records` to bind a user to that role scoped to the tenant's resource URI

### Group-based role assignment

Manage permissions for teams instead of individual users. Create a group via POST `/v1/groups`, add members, and assign roles to the group via an access record. When a new hire joins, adding them to the group instantly grants every permission the group has - no per-user record updates required. Removing them is a single DELETE.

Example prompt: POST `/v1/groups` with a name and member list, then POST `/v1/records` linking the group to an admin role on the target resource

### Agent authorization gate

Before an AI agent executes a sensitive action on behalf of a user, gate it on an Authress permission check. The agent calls GET `/v1/users/{userId}/resources/{resourceUri}/permissions/{permission}` with the user it is acting for and only proceeds on success. Through Jentic the Authress service-client token is held in the credential vault, so the agent can perform the check without holding a long-lived admin secret.

Example prompt: Verify the acting user has the 'invoices:write' permission on resource invoices/{id} before calling the downstream payment API

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/users/{userId}/resources/{resourceUri}/permissions/{permission}` | Verify a single permission for a user on a resource |
| GET | `/v1/users/{userId}/resources` | List every resource a user can access |
| POST | `/v1/records` | Create an access record granting roles to a user or group |
| GET | `/v1/records` | List access records |
| POST | `/v1/groups` | Create a group of users |
| POST | `/v1/invites` | Invite a user into a tenant |
| GET | `/v1/users/{userId}/resources/{resourceUri}/roles` | Get a user's roles for a resource |

## Key resources

- **Users** — User records, identities, and per-resource permissions
- **Access Records** — Bindings between users or groups and roles on resources
- **Roles** — Reusable sets of permissions assignable to users or groups
- **Groups** — Collections of users that share role assignments
- **Resources** — Hierarchical resource configurations and inherited permissions
- **Tenants** — Multi-tenant boundaries with their own connections and policies
- **Service Clients** — Machine-to-machine credentials for backend integrations
- **Invites** — Email-based invitations into a tenant

## Why Jentic

- **Setup:** Wiring Authress by hand means learning its bearer auth, signing service-client requests, and mapping the right operation across roughly 75 authorization and access-record endpoints yourself. Through Jentic you install once, import Authress from the API Directory, store the signing key once, and your agent calls it.
- **Permission scoping:** Authress puts the user id in the URL path (`/v1/users/{userId}/resources/...`), so a rule can pin your agent to permission and role checks for one user: it can read that user's resource permissions and roles and nothing else. You choose the operations it may call, so writes like creating access records or groups are not included unless you add them.
- **Credential handling:** Your Authress service-client signing key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check a user permission' or 'grant a role', and Jentic returns the matching Authress operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Auth0 Management API** — Auth0 handles authentication while Authress handles authorization for the same user base
- **Okta API** — Okta provides workforce identity and SSO that Authress can layer fine-grained authorization on top of
- **Keycloak Admin API** — Keycloak is a self-hosted IAM with its own authorization services

## FAQ

### Why is there no official OpenAPI spec for Authress?

Authress does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Authress via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Authress API use?

Authress uses bearer tokens - service-client JWTs for backend integrations and end-user OAuth access tokens for user-driven calls. The Authorization header carries the token on every request. Through Jentic the service-client signing key is held in the credential vault and JWTs are minted at call time.

### How do I check whether a user has a permission with the Authress API?

Send GET `/v1/users/{userId}/resources/{resourceUri}/permissions/{permission}.` The path and resource URI are URL-encoded. A 200 response means the user has the permission, taking role assignments, group membership, and resource hierarchy inheritance into account; a 403 means denied.

### Can I model multi-tenant SaaS isolation with the Authress API?

Yes. Create a tenant per customer via `/v1/tenants`, then scope every access record to a resource URI that includes the tenant identifier (for example, tenants/acme/projects/p1). Permission checks against a different tenant URI will return 403 because no access record matches.

### What are the rate limits for the Authress API?

Authress publishes plan-based rate limits in its dashboard rather than the OpenAPI spec. Permission checks are designed for hot-path use; if you receive a 429, back off exponentially and review your plan limits at https://authress.io.

### How do I grant a user a role through Jentic?

Search Jentic for 'grant a user a role' and load the POST `/v1/records` operation. Execute it with users.userId, an array of statements specifying the role and resource URI, and Jentic injects the service-client token. Get started with Jentic One, the self-hosted execution layer.

### Can I limit what my agent is allowed to do with the Authress API?

Yes. Because you run Jentic One yourself, your own rules decide which Authress operations and credentials the agent may use. Authress puts the user id directly in the URL path, so you can pin the agent to read-only checks for a single user, letting it call GET `/v1/users/{userId}/resources/{resourceUri}/permissions/{permission}` and read that user's roles while nothing else is reachable. Write operations such as creating access records under `/v1/records` or groups under `/v1/groups` stay off limits unless you explicitly add them.