An API to deal with the Flexisip server.
The API is available under /api
A 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.
The endpoints are accessible using three different models:
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}
> x-api-key: {your-api-key}
> …
Or using a cookie:
> GET /api/{endpoint}
> Cookie: x-api-key={your-api-key}
> …
To discover the available hashing algorythm you MUST send an unauthenticated request to one of the restricted endpoints.
Only DIGEST-MD5 and DIGEST-SHA-256 are supported through the authentication layer.
A from
(consisting of the user SIP address, prefixed with sip:
) header is required to initiate the DIGEST flow.
> GET /api/{restricted-endpoint}
> from: sip:foobar@sip.example.org
> …
< 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.
GET /ping
Public
Returns pong
An account_creation_request_token
is a unique token that can be validated and then used to generate a valid account_creation_token
.
POST /account_creation_request_tokens
Public
Create and return an account_creation_request_token
that should then be validated to be used.
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:
pn_provider
the push notification providerpn_param
the push notification parameterpn_prid
the push notification unique idPOST /account_creation_tokens/using-account-creation-request-token
Public
Create an account_creation_token
using an account_creation_request_token
.
Return an account_creation_token
.
Return 404
if the account_creation_request_token
provided is not valid or expired otherwise.
JSON parameters:
account_creation_request_token
requiredPOST /account_creation_tokens
Admin
Create and return an account_creation_token
.
POST /accounts/auth_token
Public
Generate an auth_token
. To attach the generated token to an account see auth_token
attachement endpoint.
Return the auth_token
object.
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.
POST /accounts/public
Enabled on this instance
Public
Unsecure endpoint
Create an account.
Return 422
if the parameters are invalid.
Send an email with the activation key if email
is set, send an SMS otherwise.
JSON parameters:
username
required if phone
not set, unique username, minimum 6 characterspassword
required minimum 6 charactersalgorithm
required, values can be SHA-256
or MD5
domain
if not set the value is enforced to the default registration domain set in the global configurationemail
optional if phone
set, an email, set an email to the account, must be unique if ACCOUNT_EMAIL_UNIQUE
is set to true
phone
required if username
not set, optional if email
set, a phone number, set a phone number to the accountaccount_creation_token
the unique account_creation_token
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:
username
unique username, minimum 6 characterspassword
required minimum 6 charactersalgorithm
required, values can be SHA-256
or MD5
account_creation_token
the unique account_creation_token
dtmf_protocol
optional, values must be sipinfo
, sipmessage
or rfc2833
GET /accounts/{sip}/info
Public
Retrieve public information about the account.
Return 404
if the account doesn't exists.
GET /accounts/{phone}/info-by-phone
Enabled on this instance
Public
Unsecure endpoint
Retrieve public information about the account.
Return 404
if the account doesn't exists.
Return phone: true
if the returned account has a phone number.
POST /accounts/recover-by-phone
Enabled on this instance
Public
Unsecure endpoint
Send a SMS with a recovery PIN code to the phone
number provided.
Return 404
if the account doesn't exists.
JSON parameters:
phone
required the phone number to send the SMS toaccount_creation_token
the unique account_creation_token
GET /accounts/{sip}/recover/{recover_key}
Enabled on this instance
Public
Unsecure endpoint
Activate the account if the correct recover_key
is provided.
The sip
parameter can be the default SIP account or the phone based one.
Return the account information (including the hashed password) if valid.
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:
confirmation_key
the confirmation keyPOST /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:
confirmation_key
the PIN codeGET /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.
GET /accounts/me/provision
User
Provision the account by generating a fresh provisioning_token
.
Return the account object.
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:
email
the new email address, must be unique if ACCOUNT_EMAIL_UNIQUE
is set to true
POST /accounts/me/password
User 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 passwordpassword
required, the new passwordPOST /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:
username
unique username, minimum 6 characterspassword
required minimum 6 charactersalgorithm
required, values can be SHA-256
or MD5
domain
not configurable by default. Only configurable if APP_ADMINS_MANAGE_MULTI_DOMAINS
is set to true
in the global configuration. Otherwise APP_SIP_DOMAIN
is used.activated
optional, a boolean, set to false
by defaultdisplay_name
optional, stringemail
optional, must be an email, must be unique if ACCOUNT_EMAIL_UNIQUE
is set to true
admin
optional, a boolean, set to false
by default, create an admin accountphone
optional, a phone number, set a phone number to the accountdtmf_protocol
optional, values must be sipinfo
, sipmessage
or rfc2833
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
.PUT /accounts/{id}
Admin Update an existing account.
JSON parameters:
username
unique username, minimum 6 characterspassword
required minimum 6 charactersalgorithm
required, values can be SHA-256
or MD5
display_name
optional, stringemail
optional, must be an email, must be unique if ACCOUNT_EMAIL_UNIQUE
is set to true
admin
optional, a boolean, set to false
by default, create an admin accountphone
optional, a phone number, set a phone number to the accountdtmf_protocol
optional, values must be sipinfo
, sipmessage
or rfc2833
GET /accounts
Admin Retrieve all the accounts, paginated.
GET /accounts/{id}
Admin Retrieve a specific account.
POST /accounts/{id}/recover-by-email
Admin
Send the account recovery email containing a fresh provisioning_token
and confirmation_key
GET /accounts/{sip}/search
Admin Search for a specific account by sip address.
GET /accounts/{email}/search-by-email
Admin Search for a specific account by email.
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
Provision an account by generating a fresh provisioning_token
.
POST /accounts/me/phone/request
User Request a specific code by SMS JSON parameters:
phone
the phone number to send the SMSPOST /accounts/me/phone
User Confirm the code received and change the phone number JSON parameters:
code
the received SMS codeReturn the updated account
GET /accounts/me/devices
User Return the user registered devices.
DELETE /accounts/me/devices/{uuid}
User Remove one of the user registered devices.
GET /accounts/me/contacts
User Return the user contacts.
GET /accounts/me/contacts/{sip}
User Return a user contact.
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.
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:
key
required, alpha numeric with dashes, lowercasecode
required, alpha numeric, lowercasePUT /accounts/{id}/actions/{action_id}
Admin Create an account action.
JSON parameters:
key
required, alpha numeric with dashes, lowercasecode
required, alpha numeric, lowercaseDELETE /accounts/{id}/actions/{action_id}
Admin Delete an account related action.
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:
key
required, alpha numeric with dashes, lowercasePUT /account_types/{id}
Admin Update an account type.
JSON parameters:
key
required, alpha numeric with dashes, lowercaseDELETE /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.
POST /messages
Admin Send a message over SIP.
JSON parameters:
to
required, SIP address of the receiverbody
required, content of the messageGET /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.
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.
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}?reset_password
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.
URL parameters:
reset_password
optional, reset the password while doing the provisioningGET /provisioning/qrcode/{provisioning_token}?reset_password
Public Return a QRCode that points to the provisioning URL.
URL parameters:
reset_password
optional, reset the password while doing the provisioningGET /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.
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.