Auth gRPC (ValidateToken, ValidateAgent)
Internal AuthService RPCs consumed by the proxy — not exposed on the public internet.
The auth service exposes ibex.auth.v1.AuthService on IBEX_GRPC_PORT (default 9091). The proxy is the primary caller. Management RPCs (CreateToken, RevokeToken, ListTokens) are available on the same service — see Issuing API keys.
Service definition
Full AuthService surface from the proto (proxy hot path uses Validate*; token lifecycle uses Create/Revoke/List):
service AuthService {
rpc ValidateToken(ValidateTokenRequest) returns (ValidateTokenResponse);
rpc ValidateAgent(ValidateAgentRequest) returns (ValidateAgentResponse);
rpc CreateToken(CreateTokenRequest) returns (CreateTokenResponse);
rpc RevokeToken(RevokeTokenRequest) returns (RevokeTokenResponse);
rpc ListTokens(ListTokensRequest) returns (ListTokensResponse);
rpc IssuePolicySnapshot(IssuePolicySnapshotRequest) returns (IssuePolicySnapshotResponse);
}Source: packages/proto/proto/ibex/auth/v1/auth.proto
ValidateToken
Called on every protected proxy request before the handler reads the body. No caller metadata is required on the hot path.
RPC: ibex.auth.v1.AuthService/ValidateTokenParse and verify a bearer PAT; return tenant context on success.
Request
| Parameter | Type | Description |
|---|---|---|
access_tokenRequired | string | Full bearer value from Authorization header (e.g. ibex_pat_…). Never log in implementations. |
Response (success)
| Parameter | Type | Description |
|---|---|---|
org_idRequired | string (uuid) | Organization scope for RLS and rate-limit keys. |
permissionsRequired | int64 | Permission bitmap — see ADR-0009 and packages/permissions. |
agent_id | string (uuid) | Optional: agent_id, user_id, token_id, expires_at when present on token. |
gRPC status codes
| gRPC code | Meaning |
|---|---|
OK | Token valid |
Unauthenticated | Missing, malformed, expired, or revoked token |
Internal | Postgres or hashing failure (logged server-side) |
DeadlineExceeded | Exceeded proxy-side validate budget |
Proxy maps transport failures to HTTP 503 SERVICE_DEGRADED. See Errors.
ValidateAgent
Called after ValidateToken on protected routes. Confirms X-IBEX-Agent-ID belongs to the token org and is active.
RPC: ibex.auth.v1.AuthService/ValidateAgentRequest
| Parameter | Type | Description |
|---|---|---|
agent_idRequired | string (uuid) | Value from X-IBEX-Agent-ID header. |
org_idRequired | string (uuid) | Org from ValidateToken response — never from the URL alone. |
Response (success)
| Field | Type | Description |
|---|---|---|
agent_id | uuid string | Echo of verified agent |
org_id | uuid string | Echo of verified org |
status | string | active, paused, suspended, or archived |
gRPC status codes
| gRPC code | Proxy HTTP | IBEX code |
|---|---|---|
OK | 200 (handler continues) | — |
PermissionDenied | 403 | AGENT_NOT_AUTHORIZED or AGENT_SUSPENDED |
InvalidArgument | 400 | validation failure |
Unavailable / transport error | 503 | AUTH_UNAVAILABLE |
Cross-org agent lookups return PermissionDenied, not NotFound. Policy: ADR-0016.
IssuePolicySnapshot
Called by the proxy after ValidateAgent on protected routes (GAP-002). Mints an immutable RS256-signed policy-snapshot.v1 envelope binding org, subject, selected agent, permissions, epoch, and issue/expiry times. The envelope is verified locally by the proxy against IBEX_PROXY_POLICY_PUBLIC_KEYS before any effect.
RPC: ibex.auth.v1.AuthService/IssuePolicySnapshotRequest
| Field | Type | Description |
|---|---|---|
agent_id | uuid string | Selected agent; required for agent-scoped tokens and must equal the token binding. Org-scoped tokens may select any agent in the org (the proxy previously verified membership). |
Caller identity (org, token/subject, permissions) comes from the authenticated bearer metadata — never from request fields.
Response (success)
| Field | Type | Description |
|---|---|---|
envelope.algorithm | string | Always RS256 |
envelope.key_id | string | Policy-signing key id (for rotation) |
envelope.payload | bytes | JCS-canonical policy-snapshot.v1 claims JSON |
envelope.signature | bytes | RSA PKCS#1 v1.5 SHA-256 signature over payload |
gRPC status codes
| gRPC code | Proxy HTTP | IBEX code |
|---|---|---|
OK | 200 (handler continues) | — |
Unauthenticated | 401 | INVALID_TOKEN |
PermissionDenied | 403 | AGENT_NOT_AUTHORIZED |
InvalidArgument | 400 | validation failure |
FailedPrecondition | 503 | SNAPSHOT_UNAVAILABLE (signing key not configured) |
Unavailable / transport error | 503 | SNAPSHOT_UNAVAILABLE |
TTL defaults to 60s; consumers bound accepted age per operation class (30s mutation, 60s read, 5s clock skew).
Example (grpcurl)
grpcurl -plaintext -d '{"access_token":"ibex_pat_…LOCALDEVELOPMENTONLY"}' \
localhost:9091 ibex.auth.v1.AuthService/ValidateTokenRequires make db-seed, running auth, and make proto-gen stubs.
Related
- Authentication — required HTTP headers
- Errors — HTTP envelope for proxy-facing failures
Was this page helpful?
Last updated on