Appearance
auth
23 endpoints at a glance
| Method | Path | Summary |
|---|---|---|
GET | /account/api-keys/ | List Keys |
POST | /account/api-keys/ | Create Key |
DELETE | /account/api-keys/{key_id} | Revoke Key |
GET | /admin/api-keys/ | List All Keys |
DELETE | /admin/api-keys/{key_id} | Admin Revoke Key |
GET | /admin/api-keys/stats/ | Get Admin Stats |
POST | /auth/forgot-password | Forgot Password |
POST | /auth/login | Login |
POST | /auth/logout | Logout |
GET | /auth/me | Me |
PATCH | /auth/me | Update Me |
PATCH | /auth/me/api-key | Update Api Key |
POST | /auth/me/api-key/test | Test Api Key |
PATCH | /auth/me/email | Update Email |
POST | /auth/me/password | Change Password |
POST | /auth/register | Register |
POST | /auth/reset-password | Reset Password |
GET | /auth/users/ | List Users |
POST | /auth/users/ | Create User |
DELETE | /auth/users/{username} | Delete User |
PATCH | /auth/users/{username} | Update User |
POST | /auth/users/{username}/password | Admin Reset Password |
POST | /auth/users/{username}/send-reset | Admin Send Reset |
auth
Login
POST
/auth/login
Verify credentials, set the session cookie, return the user.
Generic 401 on any failure — never leak whether the username
exists. Audited (auth.login) on both the success and the
failed path; recorded explicitly rather than via the dependency
because there is no actor until this call succeeds.
Request Body
application/json
JSON "username": "string", "password": "string"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Register
POST
/auth/register
Self-serve signup. Creates a viewer and auto-logs in.
Admins are still admin-created via POST /auth/users/.
Self-registration intentionally has no role field on the wire.
Audited (auth.register); recorded explicitly since the actor
only comes into existence as a result of this call.
Request Body
application/json
JSON "username": "string", "password": "string"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Forgot Password
POST
/auth/forgot-password
Public self-service reset request.
Non-enumerating: always returns the same generic 200 whether or
not the identifier matches an account (or whether that account even
has an email). Only when there's a real match with an email — and
the per-account throttle hasn't tripped — do we actually mint a
token and send the link. Audited (auth.forgot_password).
Request Body
application/json
JSON "identifier": "string"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Reset Password
POST
/auth/reset-password
Public reset completion — consume a token, set the new password.
The token is single-use and time-boxed; a bad / expired / already-
used token gets a generic 400. On success every other outstanding
token for the account is also burned. Does not auto-login — the user
signs in with the new password. Audited (auth.password_reset).
Request Body
application/json
JSON "token": "string", "new_password": "string"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Logout
Me
Update Me
Change Password
Update Email
PATCH
/auth/me/email
Set or clear the caller's email. Optional, but required to use
the self-service password-reset flow. Unique when set.
Parameters
Header Parameters
authorization
x-api-key
Request Body
application/json
JSON "email": "string"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Update Api Key
PATCH
/auth/me/api-key
Set or clear the caller's RIPE Atlas API key.
The stored value is never echoed back; the response contains a
ripe_atlas_api_key.preview (last 4 chars) and set boolean.
Parameters
Header Parameters
authorization
x-api-key
Request Body
application/json
JSON "api_key": "string"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Test Api Key
POST
/auth/me/api-key/test
Probe the caller's stored RIPE Atlas API key against the real
Atlas API and report whether it can read and create measurements.
Two probes, no side effects on RIPE:
GET /api/v2/measurements/my/— basic auth check. If this
401s the key value itself is wrong, expired, or revoked.POST /api/v2/measurements/with an empty body — probes
the create-measurement permission. RIPE evaluates auth +
permissions before payload validation, so:- 401 → key authenticates but lacks the create permission.
- 400 / 422 → has the create permission; payload was
rejected for shape reasons (which is what we want).
One-off vs recurring share the same create-measurement
permission on RIPE's side; we don't try to distinguish them.
Returns {ok, read_ok, create_ok, http_read, http_create, hint}.
Read-only — never actually creates a measurement.
Parameters
Header Parameters
authorization
x-api-key
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
List Users
Create User
Delete User
Update User
Admin Reset Password
Admin Send Reset
POST
/auth/users/{username}/send-reset
Admin-triggered reset: email the user a single-use reset link
instead of setting a password by hand. Requires the target to have
an email on file. The admin (trusted) gets a truthful result.
Parameters
Header Parameters
authorization
x-api-key
Path Parameters
username*
Type
Requiredstring
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
List Keys
GET
/account/api-keys/
List the calling user's own keys, newest first.
include_revoked=true includes soft-deleted keys; default
hides them. Each row carries the public view (no hash).
Parameters
Header Parameters
authorization
x-api-key
Query Parameters
include_revoked
Type
boolean
Default
falseResponses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Create Key
POST
/account/api-keys/
Issue a new API key for the calling user.
Returns the persisted doc shape including the plaintext
secret field — surfaced exactly once. The frontend is
expected to show it in a reveal-once dialog and never store it.
Returns 400 on validation failure (empty label, unknown scope,
past-dated expiry, etc.) with a specific detail string the
creation form can echo back to the user.
Parameters
Header Parameters
authorization
x-api-key
Request Body
application/json
JSON "label": "string", "scopes": [ "string" ], "expires_at_ts": 0
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Revoke Key
DELETE
/account/api-keys/{key_id}
Soft-revoke one of the calling user's keys.
Idempotent — revoking an already-revoked key returns the same
doc unchanged. Returns 404 when the key doesn't exist OR
belongs to a different user (both cases share a response so a
caller can't probe for foreign key ids).
Parameters
Header Parameters
authorization
x-api-key
Path Parameters
key_id*
Type
Requiredstring
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Get Admin Stats
GET
/admin/api-keys/stats/
Counts blob for the admin dashboard: total, active, revoked,
expired, used-in-last-24h / 7d. Single $facet aggregation
under the hood — one round-trip regardless of branch count.
Parameters
Header Parameters
authorization
x-api-key
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
List All Keys
GET
/admin/api-keys/
Cross-user listing with optional filters.
?username=alice narrows to one user. ?status= is one of
active / revoked / expired (omit for all). Newest-
first, paginated. Each row is the public view (hash stripped).
Parameters
Header Parameters
authorization
x-api-key
Query Parameters
username
status
active = not revoked + not expired; revoked = soft-deleted; expired = past expires_at
limit
Type
integer
Default
50offset
Type
integer
Default
0Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Admin Revoke Key
DELETE
/admin/api-keys/{key_id}
Revoke any user's key. Used by admins as the ban-hammer for
a leaked secret reported through other channels.
Records revoked_by (the admin's username) on the doc — gives
the audit trail a "who killed this" pointer alongside the
"who created it". Returns 404 when the key id doesn't exist.
Parameters
Header Parameters
authorization
x-api-key
Path Parameters
key_id*
Type
Requiredstring
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}