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": "alice@example.com",
    "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\":\"alice@example.com\",\"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/audit?actor_identity=alice@example.com&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.