Auth Service API
IAM authentication, OIDC, sessions, MFA, RBAC, and admin endpoints
The Auth Service is the IAM core for the entire 505pay platform. Every other service (POS, Payments, Recon) verifies callers against the JWTs it issues. It is also a fully spec-compliant OpenID Connect provider, so external applications can federate against 505pay via standard OAuth 2.0 / OIDC flows.
Base URLs
| Environment | Hostname |
|---|---|
| Sandbox | https://sandbox.505pay.link |
| Production | https://api.505pay.link |
Auth-service routes (/token, /authorize, /userinfo, /revoke, /logout, /.well-known/*, /v1/check, /v1/introspect, /v1/admin/*) are served from the aggregating host. For k8s-internal traffic the service is also reachable in-cluster via its k8s service DNS (auth-service.<ns>.svc), but merchants and SDKs should always use the aggregating host so the same code works across environments.
OIDC discovery lives at /.well-known/openid-configuration — most OIDC client
libraries can auto-configure from that URL alone.
Authentication model
Every request to a 505pay service is authorized by a Bearer JWT issued by this service. Tokens carry three claims that downstream services act on:
sub— the user, service-account, or partner identity.tenant_id— the tenant the caller is acting within (multi-tenant isolation).roles[]— a flat list of{role, permission, scope}entries; the SDK'sRequire(permission, scope)helper walks this list in O(n) without hitting the network.
Token verification allows ±60s clock skew. Refresh-token families are tracked server-side; reuse of a rotated refresh token triggers immediate family revocation. Access-token permissions are embedded in the JWT and verified locally by the SDK — server-side role/tenant changes take effect at the next token refresh (default TTL: 15 minutes).
How to integrate
Used by the auth-console SPA. Returns a short-lived access token plus a refresh token bound to the browser session family.
curl -X POST https://sandbox.505pay.link/v1/auth/password \
-H "Content-Type: application/json" \
-d '{
"tenant_slug": "acme",
"email": "[email protected]",
"password": "..."
}'Standard OAuth 2.0 client-credentials grant. Register a confidential client via
the admin API, store its secret in your secrets manager, and exchange for an
access token at /token.
curl -X POST https://sandbox.505pay.link/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d "grant_type=client_credentials&scope=payments.read"Long-running services authenticate with a signed JWT (grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer).
Service accounts are tied to a tenant and rotated via rotateServiceAccountKey.
Conventions
- Error envelope:
{ "error": "<code>", "message": "...", "request_id": "..." }for every non-2xx response except/token, which follows RFC 6749 §5.2. - Request IDs: all responses include
X-Request-ID; surface it in client errors so support can trace any single request end-to-end. - Pagination: list endpoints accept
?page=&limit=&search=and return the shared envelope ({<resource>[], total, page, limit, total_pages}). See the Pagination guide. - CSRF: cookie-authenticated routes require a double-submit token. Bearer callers are exempt.
Production safety
The /v1/auth/signup endpoint is gated by SIGNUP_ENABLED and rate-limited
(3/IP/h + 5/email/d). Keep it disabled for production tenants and onboard
through the admin invitation flow instead.
Endpoint reference
OIDC / OAuth2
Standard OpenID Connect and OAuth 2.0 endpoints used by SPAs, CLIs, and server-to-server clients.
Auth
Password-based login, token refresh, signup, and password reset for tenant users.
User profile & sessions
Current-user identity, active sessions, and the fallback authorization probe.
MFA (TOTP)
Enroll and verify time-based one-time passwords for multi-factor authentication.
Users, roles & groups
Tenant-scoped user management, role assignments, and group membership.
List groups
List group members
List registered permissions
List roles
List users in the caller's tenant
Fetch a user
List the user's memberships with role assignments
Create a group
Add a user to a group
Create a role
Create a user in the caller's tenant
Assign a role to a user (in the caller's tenant)
Suspend a user
Update a group
Update a role
Update a user
Delete a group
Remove a user from a group
Delete a role
Soft-delete a user
Remove a role from a user
Team management
Merchant-level team management — invite, suspend, reactivate, and assign roles to team members.
List tenant team members with their assigned roles
Read one team member with role assignments + recent audit
Reactivate a previously-suspended team member
Assign a role to a team member (optionally scoped to a POS store)
Suspend a team member (revoke active sessions, block login)
Transfer the merchant_owner role to another active member (TOTP-gated)
Invite a new team member
Remove a team member from the tenant
Revoke a role from a team member
OIDC clients & service accounts
Confidential OIDC clients and machine-to-machine service accounts.
List OIDC clients
Fetch an OIDC client
List service accounts
Fetch a service account
List SNAP partners for a merchant
Get a single SNAP partner by ID
Register an OIDC client
Rotate the OIDC client secret
Create a service account
Rotate the service-account API key
Register a new SNAP-BI partner credential
Rotate the HMAC client secret of a SNAP partner
Update an OIDC client
Update a service account
Delete an OIDC client
Delete a service account
Revoke a SNAP partner (soft-delete, idempotent)
Invitations & onboarding
Invite users by email and accept invitation tokens. First-admin signup for new tenants.
Sandbox & environment
Provision a sandbox sibling tenant and switch between production and sandbox environments.
Audit log
Tenant-scoped audit log export and retention settings.
Health & metadata
Liveness/readiness probes and the machine-readable OpenAPI spec.
Ungrouped operations
36 operations in the spec are not listed in the groups file. Add their operationIds to content/docs/api/auth.groups.json.
List tenant audit-log events with optional filters
Read this tenant's non-secret policy/toggle settings
Read this tenant's SMTP transport settings (write-only view)
Read this tenant's object-storage settings (write-only view)
Public host/slug-keyed tenant branding
List the caller's in-app notifications
Get unread notification count (badge poll)
List the caller's own sessions
Read a tenant's product-module catalog (enabled flags)
Get the caller's notification preferences
Read the caller's own tenant branding (self-serve)
Exchange a one-time SSO handoff code for a session
Dry-run preview of a candidate settings change
Clear this tenant's policy override
Clear this tenant's SMTP override
Enqueue an asynchronous SMTP send-test
Clear this tenant's object-storage override
Enqueue an asynchronous object-storage test-connection
Reinstate a suspended user (Plan C / V4-17)
Enter the caller's own sandbox sibling and mint a sandbox token
Switch the active tenant (re-scope the session to another membership)
Resend a verification email
Mint a scoped tenant JWT for internal service-to-service calls
Mark all notifications as read
Change the caller's password
Create or replace this tenant's policy/toggle settings
Create or replace this tenant's SMTP transport settings
Create or replace this tenant's object-storage settings
Replace a tenant's enabled product modules (declarative full set)
Replace the caller's notification preferences
Update the caller's own tenant branding (self-serve)
Change the POS store scope on an existing role assignment
Update current user profile
Mark a single notification as read
Set a tenant's commercial class (owner or subscriber)
Revoke one of the caller's own sessions
Was this page helpful?