About & Auth.

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

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

Access model

The endpoints are accessible using three different models:

  • Public publicly accessible
  • User the endpoint can only be accessed by an authenticated user
  • Admin the endpoint can be only be accessed by an authenticated admin user

Using the API Key

You can retrieve an API Key from your account panel or using the dedicated API endpoint.

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}
> …

Or using a cookie:

> GET /api/{endpoint}
> from: sip:foobar@sip.example.org
> Cookie: 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

Ping

GET /ping

Public Returns pong

Account Creation Tokens

An account creation token is a unique token that allow the creation of a unique account.

POST /account_creation_tokens/send-by-push

Public Create and send an account_creation_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 /account_creation_tokens

Admin

Create and return an account_creation_token.

Auth Tokens

POST /accounts/auth_token

Public Generate an auth_token. To attach the generated token to an account see auth_token attachement endpoint.

GET /accounts/auth_token/{auth_token}/attach

User Attach a publicly generated authentication token to the currently authenticated account.

Return 404 if the token is non existing or invalid.

Accounts

POST /accounts/with-account-creation-token

Public Create an account using an account_creation_token. Return 422 if the parameters are invalid or if the token is expired.

JSON parameters:

GET /accounts/{sip}/info

Public Retrieve public information about the account. Return 404 if the account doesn't exists.

POST /accounts/{sip}/activate/email

Public 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

Public 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:

GET /accounts/me/api_key/{auth_token}

Public Generate and retrieve a fresh API Key from an auth_token. The auth_token must be attached to an existing account, see auth_token attachement endpoint to do so.

Return 404 if the token is invalid or not attached.

This endpoint is also setting the API Key as a Cookie.

GET /accounts/me/api_key

User Generate and retrieve a fresh API Key. This endpoint is also setting the API Key as a Cookie.

GET /accounts/me

User Retrieve the account information.

DELETE /accounts/me

User Delete the account.

POST /accounts/me/email/request

User Change the account email. An email will be sent to the new email address to confirm the operation. JSON parameters:

POST /accounts/me/password

User Change the account password. JSON parameters:

POST /accounts

Admin To create an account directly from the API. If activated is set to false a random generated confirmation_key and provisioning_token will be returned to allow further activation using the public endpoints and provision the account. Check confirmation_key_expires to also set an expiration date on that confirmation_key.

JSON parameters:

GET /accounts

Admin Retrieve all the accounts, paginated.

GET /accounts/{id}

Admin Retrieve a specific account.

GET /accounts/{sip}/search

Admin Search for a specific account by sip address.

DELETE /accounts/{id}

Admin Delete a specific account and its related information.

GET /accounts/{id}/activate

Admin Activate an account.

GET /accounts/{id}/deactivate

Admin Deactivate an account.

GET /accounts/{id}/provision

Admin Re-provision an account by generating a fresh provisioning_token.

Accounts phone number

POST /accounts/me/phone/request

User Request a specific code by SMS JSON parameters:

POST /accounts/me/phone

User Confirm the code received and change the phone number JSON parameters:

Return the updated account

Accounts devices

GET /accounts/me/devices

User Return the user registered devices.

DELETE /accounts/me/devices/{uuid}

User Remove one of the user registered devices.

Accounts contacts

GET /accounts/me/contacts

User Return the user contacts.

GET /accounts/me/contacts/{sip}

User Return a user contact.

Contacts

GET /accounts/{id}/contacts

Admin Get all the account contacts.

POST /accounts/{id}/contacts/{contact_id}

Admin Add a contact to the list.

DELETE /accounts/{id}/contacts/{contact_id}

Admin Remove a contact from the list.

Account Actions

The following endpoints will return 403 Forbidden if the requested account doesn't have a DTMF protocol configured.

GET /accounts/{id}/actions

Admin Show an account related actions.

GET /accounts/{id}/actions/{action_id}

Admin Show an account related action.

POST /accounts/{id}/actions/

Admin Create an account action.

JSON parameters:

PUT /accounts/{id}/actions/{action_id}

Admin Create an account action.

JSON parameters:

DELETE /accounts/{id}/actions/{action_id}

Admin Delete an account related action.

Account Types

GET /account_types

Admin Show all the account types.

GET /account_types/{id}

Admin Show an account type.

POST /account_types

Admin Create an account type.

JSON parameters:

PUT /account_types/{id}

Admin Update an account type.

JSON parameters:

DELETE /account_types/{id}

Admin Delete an account type.

POST /accounts/{id}/types/{type_id}

Admin Add a type to the account.

DELETE /accounts/{id}/contacts/{type_id}

Admin Remove a a type from the account.

Messages

POST /messages

Admin Send a message over SIP.

JSON parameters:

Statistics

GET /statistics/day

Admin Retrieve registrations statistics for 24 hours.

GET /statistics/week

Admin Retrieve registrations statistics for a week.

GET /statistics/month

Admin Retrieve registrations statistics for a month.

Non-API Endpoints

The following URLs are not API endpoints they are not returning JSON content and they are not located under /api but directly under the root path.

Provisioning

When an account is having an available provisioning_token it can be provisioned using the two following URL.

GET /provisioning

Public Return the provisioning information available in the liblinphone configuration file (if correctly configured).

GET /provisioning/{provisioning_token}

Public Return the provisioning information available in the liblinphone configuration file. If the provisioning_token is valid the related account information are added to the returned XML. The account is then considered as "provisioned" and those account related information will be removed in the upcoming requests (the content will be the same as the previous url).

If the account is not activated and the provisioning_token is valid. The account will be activated.

GET /provisioning/qrcode/{provisioning_token}

Public Return a QRCode that points to the provisioning URL.

GET /provisioning/me

User Return the same base content as the previous URL and the account related information, similar to the provisioning_token endpoint. However this endpoint will always return those information.

Contacts list

GET /contacts/vcard

User Return the authenticated user contacts list, in vCard 4.0 format.

Here is the format of the vCard list returned by the endpoint:

    BEGIN:VCARD
    VERSION:4.0
    KIND:individual
    IMPP:sip:schoen.tatyana@sip.linphone.org
    FN:schoen.tatyana@sip.linphone.org
    X-LINPHONE-ACCOUNT-DTMF-PROTOCOL:sipinfo
    X-LINPHONE-ACCOUNT-TYPE:phone
    X-LINPHONE-ACCOUNT-ACTION:action_key;123
    END:VCARD
    BEGIN:VCARD
    VERSION:4.0
    KIND:individual
    IMPP:sip:dhand@sip.linphone.org
    FN:dhand@sip.linphone.org
    X-LINPHONE-ACCOUNT-DTMF-PROTOCOL:sipinfo
    END:VCARD

GET /contacts/vcard/{sip}

User Return a specific user authenticated contact, in vCard 4.0 format.