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:

• pn_provider the push notification provider
• pn_param the push notification parameter
• pn_prid the push notification unique id

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:

• username unique username, minimum 6 characters
• password required minimum 6 characters
• algorithm required, values can be SHA-256 or MD5
• domain optional, the value is set to the default registration domain if not set
• token the unique token

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:

• code the code

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:

• code the PIN code

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:

• email the new email address

POST /accounts/me/password

Change the account password.

JSON parameters:

• algorithm required, values can be SHA-256 or MD5
• old_password required if the password is already set, the old password
• password required, the new password

Phone number

POST /accounts/me/phone/request

Request a specific code by SMS

JSON parameters:

• phone the phone number to send the SMS

POST /accounts/me/phone

Confirm the code received and change the phone number

JSON parameters:

• code the received SMS code

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:

• username unique username, minimum 6 characters
• password required minimum 6 characters
• algorithm required, values can be SHA-256 or MD5
• domain optional, the value is set to the default registration domain if not set
• activated optional, a boolean, set to false by default
• admin optional, a boolean, set to false by default, create an admin account
• phone optional, a phone number, set a phone number to the account
• confirmation_key_expires optional, a datetime of this format: Y-m-d H:i:s. Only used when activated is not used or false. Enforces an expiration date on the returned confirmation_key. After that datetime public email or phone activation endpoints will return 403.

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.