API docs by Redocly

Tenon-Auth API (v1)

Download OpenAPI specification:

Multi-factor authentication for your application: set up a second step for your users, and check it at sign-in. Every error is a problem detail (RFC 9457) with a stable code.

Sign-in

Start a sign-in's second step (sends the approval request or the email)

Authorizations:
bearer
Request Body schema: application/json
required
SignInContext (object) or null
factorId
required
string <uuid>
language
string or nullja|en
userId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "context": {
    },
  • "factorId": "9edc2daa-1203-44d7-9f41-d6f0d1fc180b",
  • "language": "string",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b"
}

Response samples

Content type
application/json
{
  • "approvedWith": "FACTOR",
  • "attemptsRemaining": 0,
  • "completedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "deniedReason": "NOT_ME",
  • "email": {
    },
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "factorId": "9edc2daa-1203-44d7-9f41-d6f0d1fc180b",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "push": {
    },
  • "status": "PENDING",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b"
}

A sign-in request and its status; poll it while waiting for approval

Authorizations:
bearer
path Parameters
challengeId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "approvedWith": "FACTOR",
  • "attemptsRemaining": 0,
  • "completedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "deniedReason": "NOT_ME",
  • "email": {
    },
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "factorId": "9edc2daa-1203-44d7-9f41-d6f0d1fc180b",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "push": {
    },
  • "status": "PENDING",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b"
}

Pass the second step with a recovery code or an access pass

Authorizations:
bearer
path Parameters
challengeId
required
string <uuid>
Request Body schema: application/json
required
code
required
string [ 0 .. 64 ] characters

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "challenge": {
    },
  • "recoveryCodesRemaining": 0,
  • "verified": true
}

Check a code the user typed

Authorizations:
bearer
path Parameters
challengeId
required
string <uuid>
Request Body schema: application/json
required
code
required
string\d{6}

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "challenge": {
    },
  • "verified": true
}

Methods

Which methods the organization offers

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "email": {
    },
  • "push": true,
  • "totp": true
}

A user's methods

Authorizations:
bearer
path Parameters
userId
required
string <uuid>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Start setting up a method: authenticator codes (TOTP), sign-in approval (PUSH) or email codes (EMAIL)

Authorizations:
bearer
path Parameters
userId
required
string <uuid>
Request Body schema: application/json
required
email
string or null [ 0 .. 254 ] characters
label
string or null [ 0 .. 100 ] characters
language
string or nullja|en
type
required
string
Enum: "TOTP" "PUSH" "EMAIL"

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "label": "string",
  • "language": "string",
  • "type": "TOTP"
}

Response samples

Content type
application/json
{
  • "email": {
    },
  • "factor": {
    },
  • "push": {
    },
  • "totp": {
    }
}

Remove a method

Authorizations:
bearer
path Parameters
userId
required
string <uuid>
factorId
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "challengeId": "007cfdcc-a46d-4340-a4c6-216ec2e4009c",
  • "claimed": true,
  • "clientIp": "string",
  • "code": "invalid_request",
  • "detail": "string",
  • "errors": [
    ],
  • "instance": "string",
  • "lockedUntil": "2019-08-24T14:15:22Z",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "retryAfter": "2019-08-24T14:15:22Z",
  • "status": 0,
  • "title": "string",
  • "type": "http://example.com"
}

Finish setting up a method with its first code (TOTP, EMAIL)

Authorizations:
bearer
path Parameters
userId
required
string <uuid>
factorId
required
string <uuid>
Request Body schema: application/json
required
code
required
string\d{6}

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "activatedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "emailHint": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "label": "string",
  • "status": "PENDING",
  • "type": "TOTP"
}

Users

Find a user by external ID, without creating one

Authorizations:
bearer
query Parameters
externalId
required
string

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "displayName": "string",
  • "externalId": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Create a user, or get the existing one with this external ID

Authorizations:
bearer
Request Body schema: application/json
required
displayName
string or null [ 0 .. 255 ] characters
externalId
required
string [ 0 .. 255 ] characters

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "externalId": "string"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "displayName": "string",
  • "externalId": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Delete a user and everything Tenon-Auth keeps about them

Authorizations:
bearer
path Parameters
userId
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "challengeId": "007cfdcc-a46d-4340-a4c6-216ec2e4009c",
  • "claimed": true,
  • "clientIp": "string",
  • "code": "invalid_request",
  • "detail": "string",
  • "errors": [
    ],
  • "instance": "string",
  • "lockedUntil": "2019-08-24T14:15:22Z",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "retryAfter": "2019-08-24T14:15:22Z",
  • "status": 0,
  • "title": "string",
  • "type": "http://example.com"
}

Get a user

Authorizations:
bearer
path Parameters
userId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "displayName": "string",
  • "externalId": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Change the name shown in authenticator apps

Authorizations:
bearer
path Parameters
userId
required
string <uuid>
Request Body schema: application/json
required
displayName
string or null [ 0 .. 255 ] characters

Responses

Request samples

Content type
application/json
{
  • "displayName": "string"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "displayName": "string",
  • "externalId": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Recovery

Issue a one-time access pass (helpdesk, after checking who is asking)

Authorizations:
bearer
path Parameters
userId
required
string <uuid>
Request Body schema: application/json
required
issuedBy
string or null [ 0 .. 100 ] characters

Responses

Request samples

Content type
application/json
{
  • "issuedBy": "string"
}

Response samples

Content type
application/json
{
  • "accessPass": "string",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

How many recovery codes the user has left

Authorizations:
bearer
path Parameters
userId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "remaining": 0
}

New recovery codes, replacing the user's old ones

Authorizations:
bearer
path Parameters
userId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "codes": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z"
}

Remembered devices

Remember this browser after a sign-in, so it can skip the second step

Authorizations:
bearer
path Parameters
userId
required
string <uuid>
Request Body schema: application/json
required
challengeId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "challengeId": "007cfdcc-a46d-4340-a4c6-216ec2e4009c"
}

Response samples

Content type
application/json
{
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "token": "string"
}

Whether a remembered browser may skip the second step

Authorizations:
bearer
path Parameters
userId
required
string <uuid>
Request Body schema: application/json
required
token
required
string [ 0 .. 200 ] characters

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "trusted": true
}