Simple Auth API API Reference
The simple auth API
API Endpoint
http://example.com/api/v1Terms of Service: http://swagger.io/terms/
Contact: support@swagger.io
Version: 1.0
Authentication
ApiKeyAuth
type
apiKey
name
Authorization
in
header
SessionAuth
type
apiKey
name
auth
in
cookie
Account
Get Account
Get details about account
200 OK
OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"auth": {
"local": {
"requireOldPassword": "boolean",
"twofactor": "boolean",
"twofactorallowed": "boolean",
"username": "string"
},
"oidc": [
{
"icon": "string",
"name": "string",
"provider": "string",
"subject": "string"
}
]
},
"created": "string",
"email": "sa@example.com",
"id": "00000000-0000-0000-0000-000000000000",
"name": "John Smith"
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (404 Not Found)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Create Account
Create a new account object
Create request
createSession:
boolean
in query
Attempts to create a session on successful login
Request Content-Types: application/json
Request Example
{
"email": "string",
"password": "string (password)",
"username": "string"
}
200 OK
OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"createdSession": "boolean",
"hasStipulations": "boolean",
"id": "string"
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (404 Not Found)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Get Account Audit
Get account audit trail
offset:
number
in query
Offset of record to fetch
limit:
number
in query
Limit of records to fetch, default 10
200 OK
OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"records": [
{
"level": "string",
"message": "string",
"module": "string",
"ts": "string"
}
]
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (404 Not Found)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Check username is in use
Check if username is already in use
Request
Request Content-Types: application/json
Request Example
{
"username": "string"
}
200 OK
OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"exists": "boolean",
"username": "string"
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (404 Not Found)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Auth
Get tokens
Get tokens associated with account
200 OK
OK
400 Bad Request
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"tokens": [
{
"client_id": "string",
"client_name": "string",
"created": "string",
"expires": "string",
"short_token": "string",
"type": "string"
}
]
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (404 Not Found)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Client Info
Gets information about oauth2 client
client_id:
string
in path
OAuth2 Client ID
200 OK
OK
404 Not Found
Not Found
500 Internal Server Error
Not Found
Response Content-Types: application/json
Response Example (200 OK)
{
"author": "string",
"author_url": "string",
"name": "string"
}
Response Example (404 Not Found)
{
"error": "string",
"error_description": "string"
}
Response Example (500 Internal Server Error)
{
"error": "string",
"error_description": "string"
}
Authentication Grant Code
Called by UI to authorized a grant token. MUST pass CSRF
Request Content-Types: application/json
Request Example
{
"auto": "boolean",
"client_id": "string",
"redirect_uri": "string",
"response_type": "string",
"scope": "string",
"state": "string"
}
200 OK
OK
400 Bad Request
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"code": "string",
"state": "string"
}
Response Example (400 Bad Request)
{
"error": "string",
"error_description": "string"
}
Response Example (404 Not Found)
{
"error": "string",
"error_description": "string"
}
Response Example (500 Internal Server Error)
{
"error": "string",
"error_description": "string"
}
Grant Token
Grants a token given a various grant_type
Request Content-Types: application/json
Request Example
{
"client_id": "string",
"client_secret": "string",
"code": "string",
"grant_type": "string",
"password": "string",
"redirect_uri": "string",
"refresh_token": "string",
"scope": "string",
"totp": "string",
"username": "string"
}
200 OK
OK
400 Bad Request
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"access_token": "string",
"expires_in": "integer",
"id_token": "string",
"refresh_token": "string",
"scope": "string",
"token_type": "string"
}
Response Example (400 Bad Request)
{
"error": "string",
"error_description": "string"
}
Response Example (404 Not Found)
{
"error": "string",
"error_description": "string"
}
Response Example (500 Internal Server Error)
{
"error": "string",
"error_description": "string"
}
Revoke Token
Revoke tokens for a given client_id
client_id:
string
in query
Client ID to revoke
token:
string
in query
Optional specific token to revoke
200 OK
OK
400 Bad Request
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Example (200 OK)
{
"tokens": [
{
"client_id": "string",
"client_name": "string",
"created": "string",
"expires": "string",
"short_token": "string",
"type": "string"
}
]
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (404 Not Found)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Introspect Token
Get information about an OAuth2 token
Request Content-Types: application/json
Request Example
{
"token": "string"
}
OK
400 Bad Request
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"active": "boolean",
"aud": "string",
"client_id": "string",
"email": "string",
"exp": "integer",
"iat": "integer",
"iss": "string",
"scope": "string",
"sub": "string",
"token_type": "string",
"username": "string"
}
Response Example (400 Bad Request)
{
"error": "string",
"error_description": "string"
}
Response Example (404 Not Found)
{
"error": "string",
"error_description": "string"
}
Response Example (500 Internal Server Error)
{
"error": "string",
"error_description": "string"
}
Authenticate
Authenticate username and password. 200 on success, otherwise 403
Credentials
Request Content-Types: application/json
Request Example
{
"password": "string",
"totp": "string",
"username": "string"
}
200 OK
OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
403 Forbidden
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"id": "string",
"username": "string"
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (403 Forbidden)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (404 Not Found)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Vouch
A vouch endpoint that checks if the user is logged in via cookie. Intended to be used as auth_request in nginx for forwardauth in traefik
forward:
boolean
in query
If true, will forward to login with a 307 rather than return a 401
continue:
string
in query
Will override X-Forward headers to set the continue URL. Must follow allowedContinueURL settings
200 OK
OK
307 Temporary Redirect
Temporary Redirect
401 Unauthorized
Temporary Redirect
Response Content-Types: application/json
Response Example (200 OK)
{
"success": true
}
Response Example (307 Temporary Redirect)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Session
OneTime Authenticate
Login via onetime token and create session
token:
string
in query
OneTime token to authenticate against
302 Found
Found
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
500 Internal Server Error
Bad Request
Response Example (302 Found)
{
"success": true
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Create OneTime
Creates a new onetime token for an email
Request Content-Types: application/json
Request Example
{
"email": "sa@example.com"
}
200 OK
OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"success": true
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Session Login
Login to a session with username and password, and set cookie
Body
Request Content-Types: application/json
Request Example
{
"password": "string",
"totp": "string",
"username": "string"
}
200 OK
OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"success": true
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Session Logout
Logout session (clear cookie)
200 OK
OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"success": true
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Local
Get Local Auth
Get details about local authentication
200 OK
OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"requireOldPassword": "boolean",
"twofactor": "boolean",
"twofactorallowed": "boolean",
"username": "string"
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (404 Not Found)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Get2FA Secret
Creates a new 2fa secret to use for next steps
200 OK
OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"secret": "string"
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (404 Not Found)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Setup 2FA
Activates 2FA
Request Content-Types: application/json
Request Example
{
"code": "string",
"secret": "string (password)"
}
200 OK
OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"success": true
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (404 Not Found)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Deactivate 2FA
Deactivate 2FA
code:
string
in query
Code to check against before deactivating
200 OK
OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"success": true
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (404 Not Found)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Get2FA Secret
Gets qrcode to display to user
secret:
string
in query
Secret to generate qrcode for
200 OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: image/png
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (404 Not Found)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Change Password
Change password for local auth
Change password request
Request Content-Types: application/json
Request Example
{
"newpassword": "string",
"oldpassword": "string"
}
200 OK
OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"requireOldPassword": "boolean",
"twofactor": "boolean",
"twofactorallowed": "boolean",
"username": "string"
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (404 Not Found)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Stipulation
Satisfy Stipulation
Satisfy a stipulation on an account
Token Stipulation
Request Content-Types: application/json
Request Example
{
"account": "string",
"token": "string"
}
200 OK
OK
400 Bad Request
Bad Request
401 Unauthorized
Bad Request
404 Not Found
Bad Request
500 Internal Server Error
Bad Request
Response Content-Types: application/json
Response Example (200 OK)
{
"success": true
}
Response Example (400 Bad Request)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (401 Unauthorized)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (404 Not Found)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Response Example (500 Internal Server Error)
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
Schema Definitions
auth.grantTokenRequest: object
- client_id: string
-
General
- client_secret: string
- code: string
-
grantType == authorization_code
- grant_type: string
- password: string
- redirect_uri: string
- refresh_token: string
-
grantType == "refresh_token"
- scope: string
- totp: string
- username: string
-
grantType == "password"
Example
{
"client_id": "string",
"client_secret": "string",
"code": "string",
"grant_type": "string",
"password": "string",
"redirect_uri": "string",
"refresh_token": "string",
"scope": "string",
"totp": "string",
"username": "string"
}
auth.grantTokenResponse: object
- access_token: string
- expires_in: integer
-
Seconds access token expires in
- id_token: string
- refresh_token: string
- scope: string
- token_type: string
Example
{
"access_token": "string",
"expires_in": "integer",
"id_token": "string",
"refresh_token": "string",
"scope": "string",
"token_type": "string"
}
auth.oauth2ClientResponse: object
- author: string
- author_url: string
- name: string
Example
{
"author": "string",
"author_url": "string",
"name": "string"
}
auth.oauth2Error: object
- error: string
- error_description: string
Example
{
"error": "string",
"error_description": "string"
}
auth.oauth2GetTokenResponseToken: object
- client_id: string
- client_name: string
- created: string
- expires: string
- short_token: string
-
A short/obfuscated version of the full token for identification purposes
- type: string
Example
{
"client_id": "string",
"client_name": "string",
"created": "string",
"expires": "string",
"short_token": "string",
"type": "string"
}
auth.oauth2GetTokensResponse: object
Example
{
"tokens": [
{
"client_id": "string",
"client_name": "string",
"created": "string",
"expires": "string",
"short_token": "string",
"type": "string"
}
]
}
auth.oauth2TokenIntrospectResponse: object
- active: boolean
-
OAuth2 fields
- aud: string
- client_id: string
- email: string
-
Custom fields
- exp: integer
-
Unix timestamp expiration
- iat: integer
-
JWT extension fields
- iss: string
- scope: string
- sub: string
- token_type: string
- username: string
-
Username, if has 'username' scope
Example
{
"active": "boolean",
"aud": "string",
"client_id": "string",
"email": "string",
"exp": "integer",
"iat": "integer",
"iss": "string",
"scope": "string",
"sub": "string",
"token_type": "string",
"username": "string"
}
auth.simpleAuthRequest: object
- password: string
- totp: string
- username: string
-
Username or email
Example
{
"password": "string",
"totp": "string",
"username": "string"
}
auth.simpleAuthResponse: object
- id: string
-
Account ID
- username: string
-
Username of the account
Example
{
"id": "string",
"username": "string"
}
common.ErrorResponse: object
- error: boolean true
- message: string
- reason: string
Example
{
"error": "boolean",
"message": "A human-readable message",
"reason": "machine-code"
}
v1.changePasswordRequest: object
- newpassword: string
- oldpassword: string
-
Not required if source is one-time (eg reset link)
Example
{
"newpassword": "string",
"oldpassword": "string"
}
v1.checkUsernameResponse: object
- exists: boolean
- username: string
Example
{
"exists": "boolean",
"username": "string"
}
v1.createAccountRequest: object
- email: string
- password: string (password)
- username: string
Example
{
"email": "string",
"password": "string (password)",
"username": "string"
}
v1.createAccountResponse: object
- createdSession: boolean
-
Did create session
- hasStipulations: boolean
-
Upon success creating, whether or not account needs email
- id: string
-
ID of the created user
Example
{
"createdSession": "boolean",
"hasStipulations": "boolean",
"id": "string"
}
v1.getAccountAuditRecordResponse: object
- level: string
- message: string
- module: string
- ts: string
Example
{
"level": "string",
"message": "string",
"module": "string",
"ts": "string"
}
v1.getAccountAuditResponse: object
Example
{
"records": [
{
"level": "string",
"message": "string",
"module": "string",
"ts": "string"
}
]
}
v1.getAccountAuthProviderResponse: object
Example
{
"local": {
"requireOldPassword": "boolean",
"twofactor": "boolean",
"twofactorallowed": "boolean",
"username": "string"
},
"oidc": [
{
"icon": "string",
"name": "string",
"provider": "string",
"subject": "string"
}
]
}
v1.getAccountOIDCAuthResponse: object
- icon: string
- name: string
- provider: string
- subject: string
Example
{
"icon": "string",
"name": "string",
"provider": "string",
"subject": "string"
}
v1.getAccountResponse: object
- auth: v1.getAccountAuthProviderResponse
- created: string
- email: string
- id: string
- name: string
Example
{
"auth": {
"local": {
"requireOldPassword": "boolean",
"twofactor": "boolean",
"twofactorallowed": "boolean",
"username": "string"
},
"oidc": [
{
"icon": "string",
"name": "string",
"provider": "string",
"subject": "string"
}
]
},
"created": "string",
"email": "sa@example.com",
"id": "00000000-0000-0000-0000-000000000000",
"name": "John Smith"
}
v1.getLocalLoginResponse: object
- requireOldPassword: boolean
- twofactor: boolean
- twofactorallowed: boolean
- username: string
Example
{
"requireOldPassword": "boolean",
"twofactor": "boolean",
"twofactorallowed": "boolean",
"username": "string"
}
v1.loginRequest: object
- password: string
- totp: string
- username: string
Example
{
"password": "string",
"totp": "string",
"username": "string"
}
v1.tfaActivateRequest: object
- code: string
- secret: string (password)
Example
{
"code": "string",
"secret": "string (password)"
}