Flexisip API

An API to deal with the Flexisip server

The API is available under /api

A from (consisting of the user SIP address, prefixed with sip:), content-type and accept HTTP headers are required to use the API properly

> GET /api/{endpoint}
> from: sip:foobar@sip.example.org
> content-type: application/json
> accept: application/json

Authentication

Restricted endpoints are protected using a DIGEST authentication or an API Key mechanisms.

Using the API Key

To authenticate using an API Key, you need to authenticate to your account panel and being an administrator.

On your panel you will then find a form to generate your personnal key.

You can then use your freshly generated key by adding a new x-api-key header to your API requests:

    > GET /api/{endpoint}
    > from: sip:foobar@sip.example.org
    > x-api-key: {your-api-key}
    > …

Using DIGEST

To discover the available hashing algorythm you MUST send an unauthenticated request to one of the restricted endpoints.
For the moment only DIGEST-MD5 and DIGEST-SHA-256 are supported through the authentication layer.

> GET /api/{restricted-endpoint}
> …

< HTTP 401
< content-type: application/json
< www-authenticate: Digest realm=test,qop=auth,algorithm=MD5,nonce="{nonce}",opaque="{opaque}"
< www-authenticate: Digest realm=test,qop=auth,algorithm=SHA-256,nonce="{nonce}",opaque="{opaque}"

You can find more documentation on the related IETF RFC-7616.

Endpoints

Public endpoints

GET /ping

Returns pong

Accounts

POST /tokens

Send a token using a push notification to the device.

Return 403 if a token was already sent, or if the tokens limit is reached for this device.

Return 503 if the token was not successfully sent.

JSON parameters:

POST /accounts/with-token

Create an account using a token.

Return 422 if the parameters are invalid or if the token is expired.

JSON parameters:

GET /accounts/{sip}/info

Retrieve public information about the account.

Return 404 if the account doesn't exists.

POST /accounts/{sip}/activate/email

Activate an account using a secret code received by email.

Return 404 if the account doesn't exists or if the code is incorrect, the validated account otherwise.

JSON parameters:

POST /accounts/{sip}/activate/phone

Activate an account using a pin code received by phone.

Return 404 if the account doesn't exists or if the code is incorrect, the validated account otherwise.

JSON parameters:

User authenticated endpoints

Those endpoints are authenticated and requires an activated account.

GET /accounts/me

Retrieve the account information.

DELETE /accounts/me

Delete the account.

POST /accounts/me/email/request

Change the account email. An email will be sent to the new email address to confirm the operation.

JSON parameters:

POST /accounts/me/password

Change the account password.

JSON parameters:

Phone number

POST /accounts/me/phone/request

Request a specific code by SMS

JSON parameters:

POST /accounts/me/phone

Confirm the code received and change the phone number

JSON parameters:

Return the updated account

Devices

GET /accounts/me/devices

Return the user registered devices.

DELETE /accounts/me/devices/{uuid}

Remove one of the user registered devices.

Admin endpoints

Those endpoints are authenticated and requires an admin account.

POST /accounts

To create an account directly from the API.

If activated is set to false a random generated confirmation_key will be returned to allow further activation using the public endpoints. Check confirmation_key_expires to also set an expiration date on that confirmation_key.

JSON parameters:

GET /accounts

Retrieve all the accounts, paginated.

GET /accounts/{id}

Retrieve a specific account.

DELETE /accounts/{id}

Delete a specific account and its related information.

GET /accounts/{id}/activate

Activate an account.

GET /accounts/{id}/deactivate

Deactivate an account.