Reference

Basics

Below is a quick guide on how to integrate Almefy in your project to test it easily. We are preparing a comprehensive documentation covering all possible use cases and parameters.

Notice: This documentation is work in progress.

Authentication

We use signed Json Web Tokens (JWT) for API authentication. To provide maximum security, we also use additional claims related to the request.

Response Codes

These are the general response codes used by the Almefy API. If special handling is required, the appropriate response codes are noted below at each section.

Code	Description
200	Ok, resource was updated
201	Ok, resource was created
202	Ok, request was accepted
204	Ok, but no content is returned
400	Submitted data is invalid
401	Unauthorized access
403	Forbidden, insufficient credentials
404	Resource not Found
410	Resource is gone
423	Resource is locked
429	Too many requests
500	Something went wrong on Almefy's end

Request Errors

Whenever an error occurs, the API will return a response structure similar to this (based on the "Problem Details" described in RFC7807):

{
  "type": "https:\/\/docs.almefy.com\/api\/errors.html",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Full authentication is required to access this resource.",
  "instance": "\/v1\/entity\/identities\/enroll"
}

Invalid Data

Whenever invalid data is submitted, the 400 status code is returned to the client, with a response structure similar to this (based on the "Problem Details" described in RFC7807):

{
  "type": "https:\/\/docs.almefy.com\/api\/errors.html",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation errors occurred. Please confirm the fields and submit again.",
  "instance": "\/v1\/entity\/challenges",
  "errors": {
    "authType": [
      {
        "code": "8e179f1b-97aa-4560-a02f-2a8b42e49df7",
        "message": "The value you selected is not a valid choice."
      }
    ]
  }
}

The errors object enumerates all fields that raised errors, and each field provides a code constant, and a message description.

Identities

Create Identity

POST /v1/entity/identities

Retrieve Identity

GET /v1/entity/identities/:identifier

Update Identity

POST /v1/entity/identities/:identifier

Delete Identity

Delete Identity on the Almefy cloud. A User with this identifier won't be able to authenticate using Almefy anymore.

DELETE /v1/entity/identities/:identifier

Parameter	Type	Description
identifier	String	Unique identifier for Identity (email, username, id, hash, ...)

Response

Code	Description
204	Identity was deleted
404	Identity does not exist

List all Identities

GET /v1/entity/identities

Enroll Identity

Start enrollment process for Identity by creating an Enrollment Token, which can be used to provision a Device.

POST /v1/entity/identities/enroll

Parameter	Type	Description
identifier	String	Unique identifier for Identity (email, username, id, hash, ...)
nickname	String	Human readable nickname, if identifier is id/hash
sendEmail	Boolean	If enabled, you can use Almefy to send the enrollment Email
sendEmailTo	String	The address to send the email to
sendEmailLocale	String	Any locale or language for the email
role	String	A custom user role. ROLE_USER is default
timeout	Integer	Overwrite enrollment timeout if necessary

Note: Bold parameters are mandatory, Italic optional

Response

id: Enrollment Token Id
createdAt: UTC Date
expiresAt: UTC Date
base64ImageData: Enrollment Image Data
identity: # Identity to Enroll
  id: Identity Id
  createdAt: UTC Date
  locked: Boolean
  identifier: Unique identifier for Identity
  nickname: Readable nickname in case identifier is any Id/Hash
  label: A helper field that displays nickname instead of identifier if provided
  role: A role associated with this Identity during enrollment
  tokens: # Array of Devices associated with Identity
    id: Token Id
    createdAt: UTC Date
    name: A displayable Device name (model and label concatenated)
    model: Device Model
    label: Custom Device Label

Code	Description
200	Enrollment token created for existing Identity
201	Enrollment token created for new Identity

Rename Identity

Authentication Challenges

Create Challenge

Every authentication starts by creating an Authentication Challenge that needs to be processed by the Almefy app during a common challenge-response workflow. The response provides a challenge id as part of an image. If returnAuthImageData is set to true, the response will also contain the base64 image data of enabled auth images.

POST /v1/entity/challenges

Parameter	Type	Description
key	String	The ALMEFY API key
returnAuthImageData	Boolean	Whether the auth images should be returned as base64 data, or just URLs

Note: Bold parameters are mandatory, Italic optional

Response

id: Challenge Id
createdAt: UTC Date
expiresAt: UTC Date
authType: The authentication type, currently only "web"
authImages: List of authentication image URLs
  qrcode-standard: URL
  qrcode-extended: URL
  ...
authImagesData: Array of authentication image data (base64) if "returnAuthImageData" is "true"
  qrcode-standard: Base64 image data
  qrcode-extended: Base64 image data
  ...
pollingUrl: URL for checking the signing status
authTokenUrl: URL for retrieving the authentication token once the challenge is signed
socketsUrl: URL for the Websocket server (WIP)

Check Challenge Status

Once a challenge is created, it can be checked for any status change.

GET /v1/entity/challenges/:id/status

Parameter	Type	Description
id	String	The challenge id from response above

Note: Bold parameters are mandatory, Italic optional

Please Notice

This long-polling request is being hold approximately one second, until the response returns.

Response

# The 200 status response will contain the authentication token
token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOweqwe2241dgweiIw2324ew23qd ...

Code	Description
200	Challenge was signed, the JSON response will contain a token (see also Process Auth Token)
204	Challenge was not signed yet
404	Challenge could not be found
410	Challenge has expired