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);
}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.
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