REST API Reference

jitsudo exposes a dual API: a native gRPC API and an HTTP REST gateway generated by grpc-gateway. Both APIs are served from the same jitsudod process.

API	Address	Path prefix
REST (grpc-gateway)	`http_addr` (default `:8080`)	`/api/v1alpha1/`
gRPC	`grpc_addr` (default `:8443`)	—

Authentication

All endpoints require a valid OIDC ID token in the Authorization header:

Authorization: Bearer <id-token>

Obtain a token via jitsudo login. The token is stored at ~/.jitsudo/credentials.

Elevation Requests

Create a Request

POST /api/v1alpha1/requests

Request body:

{
  "provider": "aws",
  "role": "prod-infra-admin",
  "resource_scope": "123456789012",
  "duration_seconds": 7200,
  "reason": "Investigating P1 ECS crash",
  "break_glass": false,
  "metadata": {}
}

Response:

{
  "request": {
    "id": "req_01J8KZ4F2EMNQZ3V7XKQYBD4W",
    "state": "REQUEST_STATE_PENDING",
    "requester_identity": "[email protected]",
    "provider": "aws",
    "role": "prod-infra-admin",
    "resource_scope": "123456789012",
    "duration_seconds": 7200,
    "reason": "Investigating P1 ECS crash",
    "break_glass": false,
    "created_at": "2026-03-20T16:00:00Z",
    "updated_at": "2026-03-20T16:00:00Z"
  }
}

curl example:

curl -X POST https://jitsudo.example.com/api/v1alpha1/requests \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "aws",
    "role": "prod-infra-admin",
    "resource_scope": "123456789012",
    "duration_seconds": 7200,
    "reason": "Investigating P1 ECS crash"
  }'

List Requests

GET /api/v1alpha1/requests

Query parameters:

Parameter	Description
`mine`	Filter to caller’s own requests (`true`/`false`)
`pending`	Filter to pending requests (`true`/`false`)
`requester_identity`	Filter by requester email
`state`	Filter by state (enum value)

curl example:

# List your own requests
curl "https://jitsudo.example.com/api/v1alpha1/requests?mine=true" \
  -H "Authorization: Bearer $TOKEN"

# List all pending requests
curl "https://jitsudo.example.com/api/v1alpha1/requests?pending=true" \
  -H "Authorization: Bearer $TOKEN"

Get a Request

GET /api/v1alpha1/requests/{id}

curl "https://jitsudo.example.com/api/v1alpha1/requests/req_01J8KZ4F2EMNQZ3V7XKQYBD4W" \
  -H "Authorization: Bearer $TOKEN"

Approve a Request

POST /api/v1alpha1/requests/{request_id}/approve

Request body:

{
  "comment": "Approved for INC-4421 response"
}

curl -X POST "https://jitsudo.example.com/api/v1alpha1/requests/req_01J8KZ.../approve" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"comment": "Approved"}'

Deny a Request

POST /api/v1alpha1/requests/{request_id}/deny

Request body:

{
  "reason": "Not authorized for production access"
}

Revoke a Request

POST /api/v1alpha1/requests/{request_id}/revoke

Request body:

{
  "reason": "Incident resolved"
}

Get Credentials

Retrieve the active credentials for an approved/active request. Only the requester can call this endpoint.

GET /api/v1alpha1/requests/{request_id}/credentials

Response:

{
  "grant": {
    "request_id": "req_01J8KZ4F2EMNQZ3V7XKQYBD4W",
    "credentials": [
      {"name": "AWS_ACCESS_KEY_ID", "value": "ASIA..."},
      {"name": "AWS_SECRET_ACCESS_KEY", "value": "..."},
      {"name": "AWS_SESSION_TOKEN", "value": "..."},
      {"name": "AWS_DEFAULT_REGION", "value": "us-east-1"}
    ],
    "issued_at": "2026-03-20T16:01:00Z",
    "expires_at": "2026-03-20T18:01:00Z"
  }
}

Policies

List Policies

GET /api/v1alpha1/policies

Get a Policy

GET /api/v1alpha1/policies/{id}

Apply a Policy

Create or update a policy (upsert by name).

POST /api/v1alpha1/policies

Request body:

{
  "name": "sre-eligibility",
  "type": "POLICY_TYPE_ELIGIBILITY",
  "rego": "package jitsudo.eligibility\n\ndefault allow = false\n\nallow {\n    input.user.groups[_] == \"sre\"\n}\n",
  "description": "SRE team eligibility",
  "enabled": true
}

Delete a Policy

DELETE /api/v1alpha1/policies/{id}

Evaluate a Policy (Dry-Run)

POST /api/v1alpha1/policies:eval

Request body:

{
  "input_json": "{\"user\":{\"email\":\"[email protected]\",\"groups\":[\"sre\"]},\"request\":{\"provider\":\"aws\",\"role\":\"prod-admin\",\"resource_scope\":\"123456789012\",\"duration_seconds\":3600}}",
  "type": "POLICY_TYPE_ELIGIBILITY"
}

Response:

{
  "allowed": true,
  "reason": "",
  "result_json": "{...}"
}

Audit Log

Query Audit Events

GET /api/v1alpha1/audit

Query parameters:

Parameter	Description
`actor_identity`	Filter by actor email
`provider`	Filter by provider
`request_id`	Filter by request ID
`since`	RFC3339 timestamp (events after this time)
`until`	RFC3339 timestamp (events before this time)
`page_size`	Maximum events to return (default 100, max 1000)
`page_token`	Pagination token from previous response

curl "https://jitsudo.example.com/api/v1alpha1/[email protected]&since=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

Admin

Reload Policies

Trigger the OPA engine to reload all enabled policies from the database.

POST /api/v1alpha1/admin/reload-policies

Response:

{
  "policies_loaded": 3
}

Health Endpoints

These endpoints do not require authentication:

Endpoint	Description
`GET /healthz`	Liveness check — returns `ok`
`GET /readyz`	Readiness check — verifies database connection
`GET /version`	Returns `{"version":"0.1.0","api_versions":["v1alpha1"]}`

Request State Enum

Proto value	JSON string	Description
`REQUEST_STATE_PENDING`	`PENDING`	Awaiting approver action
`REQUEST_STATE_APPROVED`	`APPROVED`	Approved, credentials not yet fetched
`REQUEST_STATE_REJECTED`	`REJECTED`	Denied
`REQUEST_STATE_ACTIVE`	`ACTIVE`	Credentials issued and active
`REQUEST_STATE_EXPIRED`	`EXPIRED`	Elevation window elapsed
`REQUEST_STATE_REVOKED`	`REVOKED`	Manually revoked

Policy Type Enum

Proto value	JSON string	Description
`POLICY_TYPE_ELIGIBILITY`	`ELIGIBILITY`	Eligibility policy
`POLICY_TYPE_APPROVAL`	`APPROVAL`	Approval policy

gRPC

The gRPC service definition is available at api/proto/jitsudo/v1alpha1/service.proto in the GitHub repository. The protobuf definitions are managed via buf.build.

Connect to the gRPC endpoint at grpc_addr (default :8443). Use the pkg/client Go package for programmatic access.