Skip to main content

API Overview

Rampart exposes a RESTful JSON API for all identity and access management operations. Every feature available in the admin console or CLI is backed by this API, making it the single source of truth for integrations, automation, and custom tooling.

Complete Endpoint Reference​

All endpoints exposed by Rampart, organized by category. Auth column indicates: No (public), Yes (Bearer token required), Admin (admin role required).

Authentication​

MethodPathAuthDescription
POST/registerNoUser self-registration
POST/loginNoAuthenticate with username/email and password
POST/logoutNoInvalidate a session by refresh token
POST/token/refreshNoExchange a refresh token for a new access token
GET/meYesGet the authenticated user's profile

Password Reset​

MethodPathAuthDescription
POST/forgot-passwordNoRequest a password reset email
POST/reset-passwordNoReset password using a reset token

Email Verification​

MethodPathAuthDescription
POST/verify-email/sendNoSend a verification email
GET/verify-emailNoVerify email using a token (query param)

MFA -- TOTP​

MethodPathAuthDescription
POST/mfa/totp/enrollYesStart TOTP enrollment, returns QR code / secret
POST/mfa/totp/verify-setupYesConfirm TOTP setup with a verification code
POST/mfa/totp/disableYesDisable TOTP for the authenticated user
POST/mfa/totp/verifyNoVerify a TOTP code during login (uses MFA token)

MFA -- WebAuthn / Passkeys​

MethodPathAuthDescription
POST/mfa/webauthn/register/beginYesBegin WebAuthn credential registration
POST/mfa/webauthn/register/completeYesComplete WebAuthn credential registration
GET/mfa/webauthn/credentialsYesList WebAuthn credentials for the authenticated user
DELETE/mfa/webauthn/credentials/{id}YesDelete a WebAuthn credential
POST/mfa/webauthn/login/beginNoBegin WebAuthn login challenge (uses MFA token)
POST/mfa/webauthn/login/completeNoComplete WebAuthn login challenge

OAuth 2.0​

MethodPathAuthDescription
GET/oauth/authorizeNoAuthorization endpoint -- initiates user authentication
POST/oauth/authorizeNoAuthorization endpoint -- form submission handler
POST/oauth/consentNoUser consent submission
POST/oauth/tokenConditionalToken endpoint -- issues and refreshes tokens
POST/oauth/revokeYesRevocation endpoint -- invalidates tokens (RFC 7009)

Social Login​

MethodPathAuthDescription
GET/oauth/social/{provider}NoInitiate social login (redirect to provider)
GET/oauth/social/{provider}/callbackNoSocial login callback (GET)
POST/oauth/social/{provider}/callbackNoSocial login callback (POST, e.g. Apple Sign In)

SAML​

MethodPathAuthDescription
GET/saml/providersNoList configured SAML identity providers
GET/saml/{providerID}/metadataNoSP metadata XML for a SAML provider
GET/saml/{providerID}/loginNoInitiate SAML SSO login (redirect to IdP)
POST/saml/{providerID}/acsNoAssertion Consumer Service (receives SAML response)

OIDC Discovery​

MethodPathAuthDescription
GET/.well-known/openid-configurationNoOpenID Connect discovery document
GET/.well-known/jwks.jsonNoJSON Web Key Set for token verification

SCIM 2.0 Provisioning​

MethodPathAuthDescription
GET/scim/v2/ServiceProviderConfigAdminSCIM service provider configuration
GET/scim/v2/ResourceTypesAdminSCIM resource type definitions
GET/scim/v2/SchemasAdminSCIM schema definitions
GET/scim/v2/UsersAdminList SCIM users
POST/scim/v2/UsersAdminCreate a SCIM user
GET/scim/v2/Users/{id}AdminGet a SCIM user
PUT/scim/v2/Users/{id}AdminReplace a SCIM user
PATCH/scim/v2/Users/{id}AdminPartially update a SCIM user
DELETE/scim/v2/Users/{id}AdminDelete a SCIM user
GET/scim/v2/GroupsAdminList SCIM groups
POST/scim/v2/GroupsAdminCreate a SCIM group
GET/scim/v2/Groups/{id}AdminGet a SCIM group
PUT/scim/v2/Groups/{id}AdminReplace a SCIM group
PATCH/scim/v2/Groups/{id}AdminPartially update a SCIM group
DELETE/scim/v2/Groups/{id}AdminDelete a SCIM group

Admin API -- Users​

MethodPathAuthDescription
GET/api/v1/admin/statsAdminDashboard statistics (user count, session count, etc.)
GET/api/v1/admin/usersAdminList users with pagination and filtering
POST/api/v1/admin/usersAdminCreate a new user
GET/api/v1/admin/users/{id}AdminGet a user by ID
PUT/api/v1/admin/users/{id}AdminUpdate a user
DELETE/api/v1/admin/users/{id}AdminDelete a user
POST/api/v1/admin/users/{id}/reset-passwordAdminAdmin password reset for a user
GET/api/v1/admin/users/{id}/sessionsAdminList sessions for a user
DELETE/api/v1/admin/users/{id}/sessionsAdminRevoke all sessions for a user

Admin API -- Organizations​

MethodPathAuthDescription
GET/api/v1/admin/organizationsAdminList organizations
POST/api/v1/admin/organizationsAdminCreate an organization
GET/api/v1/admin/organizations/{id}AdminGet an organization
PUT/api/v1/admin/organizations/{id}AdminUpdate an organization
DELETE/api/v1/admin/organizations/{id}AdminDelete an organization
GET/api/v1/admin/organizations/{id}/settingsAdminGet organization settings
PUT/api/v1/admin/organizations/{id}/settingsAdminUpdate organization settings
GET/api/v1/admin/organizations/{id}/exportAdminExport organization configuration
POST/api/v1/admin/organizations/{id}/importAdminImport organization configuration

Admin API -- Compliance​

MethodPathAuthDescription
GET/api/v1/compliance/soc2AdminGenerate SOC 2 compliance report
GET/api/v1/compliance/gdprAdminGenerate GDPR compliance report
GET/api/v1/compliance/hipaaAdminGenerate HIPAA compliance report
GET/api/v1/compliance/audit-exportAdminExport audit trail

Health & Monitoring​

MethodPathAuthDescription
GET/healthzNoLiveness probe -- returns 200 if server is running
GET/readyzNoReadiness probe -- returns 200 if database is healthy, 503 otherwise
GET/metricsTokenPrometheus metrics (requires RAMPART_METRICS_TOKEN)

Design Principles​

Rampart's API follows these core design principles:

  • REST -- Resources are identified by URLs, manipulated with standard HTTP methods (GET, POST, PUT, DELETE), and represented as JSON.
  • Versioned -- The Admin API is versioned via the URL path (/api/v1/). Breaking changes only happen in new major versions.
  • Consistent -- All endpoints follow the same conventions for errors, pagination, filtering, and response envelopes.
  • Specification-compliant -- OAuth 2.0 and OpenID Connect endpoints follow their respective RFCs exactly (RFC 6749, RFC 7009, RFC 7517, RFC 7636, RFC 7662).
  • API-first -- Every feature is accessible via the API before it appears in the admin console or CLI.

Base URL​

All API endpoints are relative to your Rampart instance base URL:

https://your-rampart-instance

The API is organized into these endpoint groups:

GroupBase PathPurpose
Authentication/Registration, login, logout, token refresh, password reset, email verification
User Profile/meAuthenticated user's own profile
MFA/mfa/TOTP and WebAuthn enrollment, verification, and management
OAuth / OIDC/oauth/Token issuance, authorization, consent, revocation, social login
SAML/saml/SAML SP metadata, login initiation, and assertion consumer
Discovery/.well-known/OpenID Connect discovery and JWKS
SCIM/scim/v2/SCIM 2.0 user and group provisioning
Admin API/api/v1/admin/User, organization, session, and stats management
Compliance/api/v1/compliance/SOC 2, GDPR, HIPAA reports and audit export
Health/healthz, /readyzHealth and readiness probes

URL Convention​

  • All Admin API paths use plural nouns: /api/v1/admin/users, /api/v1/admin/organizations.
  • Individual resources are accessed by ID: /api/v1/admin/users/{user_id}.
  • Sub-resources are nested: /api/v1/admin/users/{user_id}/sessions.
  • Query parameters use snake_case.
  • No trailing slashes. Requests with trailing slashes receive a 301 redirect.

API Versioning​

The Admin API is versioned via the URL path (/api/v1/). OAuth and OIDC endpoints follow their respective RFCs and are not versioned -- their paths are stable by specification.

When a new API version is introduced, the previous version will continue to be supported for at least 12 months with deprecation notices in response headers:

Deprecation: true
Sunset: Sat, 01 Mar 2028 00:00:00 GMT
Link: <https://your-rampart-instance/api/v2/admin/users>; rel="successor-version"

Authentication​

Public Endpoints​

The following endpoints do not require authentication: /register, /login, /forgot-password, /reset-password, /verify-email/send, /verify-email, /mfa/totp/verify, /mfa/webauthn/login/*, /oauth/authorize, /oauth/social/*, /saml/*, /.well-known/*, /healthz, /readyz.

Bearer Token Endpoints​

Endpoints like /me, /mfa/totp/enroll, /mfa/totp/verify-setup, /mfa/totp/disable, and /mfa/webauthn/register/* require a valid Bearer token in the Authorization header.

curl -X GET https://your-rampart-instance/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Admin API​

All /api/v1/admin/ endpoints require a valid Bearer token belonging to a user with the admin role.

curl -X GET https://your-rampart-instance/api/v1/admin/users \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json"

OAuth Endpoints​

OAuth endpoints use standard OAuth 2.0 authentication mechanisms:

  • Confidential clients authenticate via HTTP Basic (Authorization: Basic base64(client_id:client_secret)) or by including client_id and client_secret in the request body.
  • Public clients (SPAs, mobile apps) use PKCE and do not send a client secret. Only the client_id is required.
  • Token revocation requires client authentication.

Client Authentication Methods​

MethodHeader / ParameterUse Case
client_secret_basicAuthorization: Basic base64(id:secret)Server-side applications (recommended)
client_secret_postclient_id + client_secret in bodyWhen Basic auth is not practical
noneclient_id onlyPublic clients (SPAs, mobile apps) with PKCE

Content Type​

All request and response bodies use JSON (application/json), except for the OAuth token endpoint which accepts application/x-www-form-urlencoded as required by RFC 6749.

# Authentication endpoints -- JSON body
curl -X POST https://your-rampart-instance/login \
  -H "Content-Type: application/json" \
  -d '{"identifier": "jane@example.com", "password": "SecureP@ssw0rd!"}'
# OAuth token endpoint -- form-urlencoded body
curl -X POST https://your-rampart-instance/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=my-service" \
  -d "client_secret=secret123"

Error Format​

All errors follow a consistent JSON structure:

{
  "error": "not_found",
  "error_description": "User with ID '550e8400-e29b-41d4-a716-446655440000' was not found.",
  "request_id": "req_abc123def456"
}
FieldTypeDescription
errorstringMachine-readable error code (e.g., invalid_request, not_found, forbidden)
error_descriptionstringHuman-readable message with details about what went wrong
request_idstringUnique identifier for the request, useful for support and debugging

OAuth Error Codes​

OAuth endpoints return error codes defined by RFC 6749 and RFC 7009:

Error CodeHTTP StatusMeaning
invalid_request400Missing or malformed parameter
invalid_client401Client authentication failed
invalid_grant400Authorization code or refresh token is invalid or expired
unauthorized_client400Client is not authorized for this grant type
unsupported_grant_type400The grant type is not supported
invalid_scope400Requested scope is invalid or exceeds granted scopes
access_denied403Resource owner denied the request
server_error500Unexpected internal error

Admin API Error Codes​

Error CodeHTTP StatusMeaning
bad_request400Invalid request body or parameters
unauthorized401Missing or invalid Bearer token
forbidden403Authenticated but lacks required permissions
not_found404Requested resource does not exist
conflict409Resource already exists (e.g., duplicate username or email)
validation_error422Request body failed validation
rate_limited429Too many requests
internal_error500Unexpected server error

Validation Errors​

When a request body fails validation, the response includes field-level details:

{
  "error": "validation_error",
  "error_description": "Request body failed validation.",
  "request_id": "req_abc123def456",
  "details": [
    {
      "field": "email",
      "message": "Must be a valid email address."
    },
    {
      "field": "username",
      "message": "Must be between 3 and 128 characters."
    },
    {
      "field": "password",
      "message": "Must contain at least one uppercase letter, one lowercase letter, one digit, and one special character."
    }
  ]
}

HTTP Status Code Summary​

StatusMeaning
200Success (GET, PUT, POST for token operations)
201Resource created (POST)
204Success with no content (DELETE, logout)
301Redirect (trailing slash removal)
302OAuth redirect (authorize endpoint)
400Bad request
401Authentication required or failed
403Forbidden (insufficient permissions)
404Resource not found
409Conflict (duplicate resource)
422Validation error
429Rate limited
500Internal server error

Pagination​

All list endpoints in the Admin API support cursor-based pagination. This provides consistent results even when records are added or removed between pages.

Request Parameters​

ParameterTypeDefaultDescription
limitinteger20Number of items per page (1--100)
cursorstring--Opaque cursor from a previous response
sortstringcreated_atField to sort by (varies per resource)
orderstringdescSort direction: asc or desc

Response Envelope​

All list responses use a consistent envelope:

{
  "data": [
    { "id": "usr_001", "username": "jane.doe", "email": "jane@example.com" },
    { "id": "usr_002", "username": "john.smith", "email": "john@example.com" }
  ],
  "pagination": {
    "total": 1284,
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0wMVQxMjowMDowMFoiLCJpZCI6InVzcl8wMDIifQ=="
  }
}
FieldTypeDescription
dataarrayArray of resource objects
pagination.totalintegerTotal number of matching records
pagination.limitintegerNumber of items requested per page
pagination.has_morebooleanWhether more pages exist
pagination.next_cursorstringCursor to pass as cursor parameter for the next page (absent if has_more is false)

Paginating Through Results​

# First page
curl -X GET "https://your-rampart-instance/api/v1/admin/users?limit=20" \
  -H "Authorization: Bearer <token>"

# Next page (using next_cursor from previous response)
curl -X GET "https://your-rampart-instance/api/v1/admin/users?limit=20&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0wMVQxMjowMDowMFoiLCJpZCI6InVzcl8wMDIifQ==" \
  -H "Authorization: Bearer <token>"

Continue fetching pages until has_more is false.

Filtering​

List endpoints support field-level filtering via query parameters:

# Find enabled users in a specific organization
curl -X GET "https://your-rampart-instance/api/v1/admin/users?enabled=true&organization_id=org_abc123" \
  -H "Authorization: Bearer <token>"

# Search users by email domain
curl -X GET "https://your-rampart-instance/api/v1/admin/users?search=@example.com" \
  -H "Authorization: Bearer <token>"

The search parameter performs a case-insensitive substring match against common text fields (username, email, first name, last name for users; name and slug for organizations).

Common Filter Parameters​

ParameterTypeAvailable OnDescription
searchstringUsers, Organizations, ClientsFree-text search across common fields
enabledbooleanUsersFilter by enabled/disabled status
organization_idstringUsers, Clients, SessionsFilter by organization
rolestringUsersFilter by role name
typestringEventsFilter by event type
fromISO 8601EventsStart of date range
toISO 8601EventsEnd of date range
user_idstringSessions, EventsFilter by user
client_idstringSessionsFilter by client

Rate Limiting​

Rampart enforces rate limits to protect against abuse. Limits are applied per client IP for unauthenticated endpoints and per access token for authenticated endpoints.

Default Limits​

Endpoint GroupLimitWindow
POST /login20 requestsper minute per IP
POST /register20 requestsper minute per IP
POST /forgot-password10 requestsper minute per IP
POST /token/refresh20 requestsper minute per IP
POST /mfa/totp/verify20 requestsper minute per IP
POST /oauth/token20 requestsper minute per IP
Admin API (read)300 requestsper minute per token
Admin API (write)60 requestsper minute per token

Rate Limit Headers​

Every response includes rate limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1709510460
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the window resets
Retry-AfterSeconds to wait before retrying (only present on 429 responses)

When rate limited, the server returns HTTP 429:

{
  "error": "rate_limited",
  "error_description": "Too many requests. Please retry after 12 seconds.",
  "request_id": "req_xyz789"
}

Rate limits are configurable in the Rampart server configuration file under the rate_limiting section.

Request IDs​

Every response includes a X-Request-Id header containing a unique identifier for the request. This ID also appears in server logs and error responses, making it straightforward to correlate client-side issues with server-side logs.

X-Request-Id: req_abc123def456

If you provide a X-Request-Id header in your request, Rampart will use your value instead of generating one. This is useful for tracing requests across multiple services.

CORS​

Cross-Origin Resource Sharing (CORS) is configured via the RAMPART_ALLOWED_ORIGINS environment variable. Rampart uses these origins to set CORS headers on all endpoints.

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Accept, Authorization, Content-Type, X-Request-Id, X-Org-Context
Access-Control-Max-Age: 300

Health Check​

Rampart exposes health endpoints for load balancers and monitoring:

curl -X GET https://your-rampart-instance/healthz
{
  "status": "ok"
}

The health endpoint (/healthz) returns HTTP 200 when the server is running. A readiness probe is available at /readyz -- it returns HTTP 200 only when the server is ready to accept traffic (database connectivity verified), and HTTP 503 when the database is unhealthy.

Idempotency​

Write operations (POST) support idempotency via the Idempotency-Key header. If you send the same request with the same idempotency key within a 24-hour window, Rampart returns the original response without performing the operation again.

curl -X POST https://your-rampart-instance/api/v1/admin/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: usr-creation-abc123" \
  -d '{
    "username": "jane.doe",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "enabled": true,
    "password": "SecureP@ssw0rd!"
  }'

PUT and DELETE operations are naturally idempotent and do not require this header.

Common curl Examples​

Register a new user​

curl -X POST https://your-rampart-instance/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jane.doe",
    "email": "jane@example.com",
    "password": "SecureP@ssw0rd!",
    "given_name": "Jane",
    "family_name": "Doe"
  }'

Log in​

curl -X POST https://your-rampart-instance/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "jane@example.com",
    "password": "SecureP@ssw0rd!"
  }'

Get current user profile​

curl -X GET https://your-rampart-instance/me \
  -H "Authorization: Bearer <access_token>"

Refresh an access token​

curl -X POST https://your-rampart-instance/token/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<refresh_token>"}'

Log out​

curl -X POST https://your-rampart-instance/logout \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<refresh_token>"}'

Check server health​

curl -X GET https://your-rampart-instance/healthz

Fetch OIDC discovery document​

curl -X GET https://your-rampart-instance/.well-known/openid-configuration