# About & Auth. 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} > 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 - Super Admin the endpoint can be only be accessed by an authenticated super admin user ### Space expiration Super Admin can configure and expiration date on Spaces (`expire_at`). If the Space is expired all the authenticated endpoint of the API will return `403`. ### Localization You can add an [`Accept-Language`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) header to your request to translate the responses, and especially errors messages, in a specific language. Currently supported languages: @php echo implode(', ', config('app.authorized_locales')) @endphp ``` > GET /api/{endpoint} > Accept-Language: fr > … < HTTP 422 < { < "message": "Le champ pseudo est obligatoire.", < "errors": { < "username": [ < 0 => "Le champ pseudo est obligatoire." < ] < } < } ``` ### Using the API Key You can retrieve an API Key from your account panel or using the dedicated API endpoint. **When generated by a User account the generated API Key will be restricted to the IP that generates it and will be destroyed if not used after some times.** **If you want a stable API Key, to integrate with another server component for example, you can generate one in the Administration Panel.** 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} > … ``` ### Using a JWT token You can use a JWT token to authenticate on the API. To do so you MUST inject it as an `Authorization: Bearer` header and configure the API with the public key of the token emitter. ``` > GET /api/{endpoint} > Authorization: Bearer {your-jwt-token} > … ``` The API will then check if the token was signed properly, is still valid and authenticate a user that is actually available in the system. ### Using DIGEST 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](https://tools.ietf.org/html/rfc7616).
# Endpoints ## Ping ### `GET /ping` Public Returns `pong` ## Spaces Manage the list of allowed `spaces`. The admin accounts declared with a `domain` that is a `super` `sip_domain` will become Super Admin. ### `GET /spaces` Super Admin Get the list of declared Spaces. ### `GET /spaces/{domain}` Super Admin Get a Space. ### `POST /spaces` Super Admin Create a new `sip_domain`. JSON parameters: * `name` **required**, the space name * `domain` **required**, the SIP domain to use, must be unique * `super` **required**, boolean, set the domain as a Super Domain * `disable_chat_feature` boolean, disable the chat feature, default to `false` * `disable_meetings_feature` boolean, disable the meeting feature, default to `false` * `disable_broadcast_feature` boolean, disable the broadcast feature, default to `true` * `hide_settings` boolean, hide the app settings, default to `false` * `hide_account_settings` boolean, disable the account settings, default to `false` * `disable_call_recordings_feature` boolean, disable the call recording feature, default to `false` * `only_display_sip_uri_username` boolean, hide the SIP uris in the app, default to `false` * `assistant_hide_create_account` boolean, disable the account creation assistant, default to `false` * `assistant_disable_qr_code` boolean, disable the QR code feature in the assistant, default to `false` * `assistant_hide_third_party_account` boolean, disable the call recording feature, default to `false` * `max_account` integer, the maximum number of accounts configurable in the app, default to `0` (infinite) * `max_accounts` integer, the maximum number of accounts that can be created in the space, default to `0` (infinite), cannot be less than the actual amount of accounts * `expire_at` date, the moment the space is expiring, default to `null` (never expire) * `copyright_text` text, the copyright text * `intro_registration_text` Markdown text, the main registration page text * `confirmed_registration_text` Markdown text, the text displayed in the registration email * `newsletter_registration_address`, the newsletter registration email address * `account_proxy_registrar_address`, the account proxy registrar address * `account_realm`, the default realm for the accounts, fallback to the domain if not set * `custom_provisioning_entries` text, the custom configuration used for the provisioning * `custom_provisioning_overwrite_all` boolean, allow the custom configuration to overwrite the default one * `provisioning_use_linphone_provisioning_header` boolean * `custom_theme` boolean, allow a custom CSS file to be loaded * `web_panel` boolean, the web panel switch * `public_registration` boolean, the public registration switch * `phone_registration` boolean, the phone registration switch * `intercom_features` boolean, the intercom features switch ### `PUT /spaces/{domain}` Super Admin Update an existing `sip_domain`. JSON parameters: * `name` **required**, the space name * `super` **required**, boolean, set the domain as a Super Domain * `disable_chat_feature` **required**, boolean * `disable_meetings_feature` **required**, boolean * `disable_broadcast_feature` **required**, boolean * `hide_settings` **required**, boolean * `hide_account_settings` **required**, boolean * `disable_call_recordings_feature` **required**, boolean * `only_display_sip_uri_username` **required**, boolean * `assistant_hide_create_account` **required**, boolean * `assistant_disable_qr_code` **required**, boolean * `assistant_hide_third_party_account` **required**, boolean * `max_account` **required**, integer * `max_accounts` **required**,integer, the maximum number of accounts that can be created in the space, default to `0` (infinite), cannot be less than the actual amount of accounts * `expire_at` **required**, date, the moment the space is expiring, set to `null` to never expire * `copyright_text` **required**, text, the copyright text * `intro_registration_text` **required**, Markdown text, the main registration page text * `confirmed_registration_text` **required**, Markdown text, the text displayed in the registration email * `newsletter_registration_address`, **required**, the newsletter registration email address * `account_proxy_registrar_address`, **required**, the account proxy registrar address * `account_realm`, **required**, the default realm for the accounts, fallback to the domain if not set * `custom_provisioning_entries` **required**, text, the custom configuration used for the provisioning * `custom_provisioning_overwrite_all` **required**, boolean, allow the custom configuration to overwrite the default one * `provisioning_use_linphone_provisioning_header` **required**, boolean * `custom_theme` **required**, boolean, allow a custom CSS file to be loaded * `web_panel` **required**, boolean, the web panel switch * `public_registration` **required**, boolean, the public registration switch * `phone_registration` **required**, boolean, the phone registration switch * `intercom_features` **required**, boolean, the intercom features switch ### `DELETE /spaces/{domain}` Super Admin Delete a domain, **be careful, all the related accounts will also be destroyed**. ### `GET /spaces/{domain}/email` Super Admin Get a space email server configuration ### `POST /spaces/{domain}/email` Super Admin Update an existing a space email server configuration. JSON parameters: * `host` **required**, the email server hostname * `port` **required**, integer, the port * `username`, the username * `password`, the password * `from_address`, email address, the sender email address * `from_name`, the sender name * `signature`, a text that will end every emails sent ### `DELETE /spaces/{domain}/email` Super Admin Delete the a space email server configuration. ## Account Creation Request Tokens 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. ## Account Creation Tokens An `account_creation_token` is a unique token that allow the creation or the validation 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` **required**, the push notification provider, must be in apns.dev, apns or fcm * `pn_param` the push notification parameter, can be null or contain only alphanumeric and underscore characters * `pn_prid` the push notification unique id, can be null or contain only alphanumeric, dashes, underscore and colon characters ### `POST /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` **required** ### `POST /account_creation_tokens/consume` User Consume an `account_creation_token` and link it to the authenticated account. Return an `account_creation_token`. Return `404` if the `account_creation_token` provided is not valid. JSON parameters: * `account_creation_token` **required** ### `POST /account_creation_tokens` Admin Create and return an `account_creation_token`. ## Account Recovery Tokens An `account_recovery_token` is a unique token that allow the recovery of an account. It can be used on the following page that also accepts a `phone` optional parameter to prefil the recovery form: {{ route('account.recovery.show.phone', ['account_recovery_token' => '_the_token_']) }} {{ route('account.recovery.show.phone', ['account_recovery_token' => '_the_token_', 'phone' => '+3312341234']) }} ### `POST /account_recovery_tokens/send-by-push` Public Create and send an `account_recovery_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` **required**, the push notification provider, must be in apns.dev, apns or fcm * `pn_param` the push notification parameter, can be null or contain only alphanumeric and underscore characters * `pn_prid` the push notification unique id, can be null or contain only alphanumeric, dashes, underscore and colon characters ## 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-accountsauthtokenauthtokenattach). 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. ## 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. Return `403` if the `max_accounts` limit of the corresponding Space is reached. JSON parameters: * `username` unique username, minimum 6 characters * `password` **required** minimum 6 characters * `algorithm` **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/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](#get-accountsauthtokenauthtokenattach) 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/services/turn` User If configured, returns valid TURN credentials following the [draft-uberti-behave-turn-rest-00 IEFT Draft](https://datatracker.ietf.org/doc/html/draft-uberti-behave-turn-rest-00). ### `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/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 password * `password` **required**, the new password ### `POST /accounts` Admin To create an account directly from the API. Return `403` if the `max_accounts` limit of the corresponding Space is reached. JSON parameters: * `username` unique username, minimum 6 characters * `password` **required** minimum 6 characters * `algorithm` **required**, values can be `SHA-256` or `MD5` * `domain` **not configurable by default**, must exist in one of the configured Spaces. Only configurable if the admin is a super admin. Otherwise the SIP domain of the corresponding space is used. * `activated` optional, a boolean, set to `false` by default * `display_name` optional, string * `email` 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 account * `phone` optional, a valid phone number, set a phone number to the account * `dtmf_protocol` optional, values must be `sipinfo`, `sipmessage` or `rfc2833` * `dictionary` optional, an associative array attached to the account, see also the related endpoints. ### `PUT /accounts/{id}` Admin Update an existing account. Ensure to resend all the parameters to not reset them. JSON parameters: * `username` unique username, minimum 6 characters * `domain` **not configurable by default**, must exist in one of the configured Spaces. Only configurable if the admin is a super admin. Otherwise the SIP domain of the corresponding space is used. * `password` **required** minimum 6 characters * `algorithm` **required**, values can be `SHA-256` or `MD5` * `display_name` optional, string * `email` 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 * `phone` optional, a valid phone number, set a phone number to the account * `dtmf_protocol` optional, values must be `sipinfo`, `sipmessage` or `rfc2833` Using this endpoint you can also set a fresh dictionnary if the parameter is set. The existing dictionary entries will be destroyed. * `dictionary` optional, an associative array attached to the account, see also the related endpoints. This endpoint also return the current `phone_change_code` and `email_change_code` if they are available. ### `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. ### `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. ### `POST /accounts/{id}/activate` Admin Activate an account. ### `POST /accounts/{id}/deactivate` Admin Deactivate an account. ### `POST /accounts/{id}/block` Admin Block an account. ### `POST /accounts/{id}/unblock` Admin Unblock an account. ### `GET /accounts/{id}/provision` Admin Provision an account by generating a fresh `provisioning_token`. ## Accounts email ### `POST /accounts/me/email/request` User Request to change the account email. An email will be sent to the new email address to confirm the operation. Will return `403` if the account doesn't have a validated Account Creation Token attached to it. JSON parameters: * `email` the new email address, must be unique if `ACCOUNT_EMAIL_UNIQUE` is set to `true` ### `POST /accounts/me/email` User Confirm the code received and change the email. Activate the account. JSON parameters: * `code` the code received by email Return the updated account. ## Accounts phone number ### `POST /accounts/me/phone/request` User Request a specific code by SMS to change the phone number. Will return `403` if the account doesn't have a validated Account Creation Token attached to it. JSON parameters: * `phone` the phone number to send the SMS ### `POST /accounts/me/phone` User Confirm the code received and change the phone number. Activate the account. JSON parameters: * `code` the received SMS code Return the updated account. ## Accounts devices ### `GET /accounts/{id/me}/devices` Admin User Return the user registered devices. ### `DELETE /accounts/{id/me}/devices/{uuid}` Admin User Remove one of the user registered devices. ## Account contacts ### `GET /accounts/me/contacts` User Return the user contacts. ### `GET /accounts/me/contacts/{sip}` User Return a user contact. ## vCards storage ### `POST /accounts/{id/me}/vcards-storage` Admin User Store a vCard. JSON parameters: * `vcard`, mandatory, a valid vCard having a mandatory `UID` parameter that is uniquelly identifying it. This `UID` parameter will then be used to manipulate the vcard through the following endpoints as `uuid`. ### `PUT /accounts/{id/me}/vcards-storage/{uuid}` Admin User Update a vCard. JSON parameters: * `vcard`, mandatory, a valid vCard having a mandatory `UID` parameter that is uniquelly identifying it and is the same as the `uuid` parameter. ### `GET /accounts/{id/me}/vcards-storage` Admin User Return the list of stored vCards ### `GET /accounts/{id/me}/vcards-storage/{uuid}` Admin User Return a stored vCard ### `DELETE /accounts/{id/me}/vcards-storage/{uuid}` Admin User Delete a stored vCard ## 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. ## Dictionary ### `GET /accounts/{id}/dictionary` Admin Get all the account dictionary entries. ### `POST /accounts/{id}/dictionary/{key}` Admin Add or update a new entry to the dictionary JSON parameters: * `value` **required**, the entry value ## External Account ### `GET /accounts/{id}/external` Admin Get the external account. ### `POST /accounts/{id}/external` Admin Create or update the external account. JSON parameters: * `username` **required** * `domain` **required** * `password` **required** * `realm` must be different than `domain` * `registrar` must be different than `domain` * `outbound_proxy` must be different than `domain` * `protocol` **required**, must be `UDP`, `TCP` or `TLS` ### `DELETE /accounts/{id}/external` Admin Delete the external account. ## 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: * `key` **required**, alpha numeric with dashes, lowercase * `code` **required**, alpha numeric, lowercase ### `PUT /accounts/{id}/actions/{action_id}` Admin Create an account action. JSON parameters: * `key` **required**, alpha numeric with dashes, lowercase * `code` **required**, alpha numeric, lowercase ### `DELETE /accounts/{id}/actions/{action_id}` Admin Delete an account related action. ## Contacts Lists ### `GET /contacts_lists` Admin Show all the contacts lists. ### `GET /contacts_lists/{id}` Admin Show a contacts list. ### `POST /contacts_lists` Admin Create a contacts list. JSON parameters: * `title` **required** * `description` **required** ### `PUT /contacts_lists/{id}` Admin Update a contacts list. JSON parameters: * `title` **required** * `description` **required** ### `DELETE /contacts_lists/{id}` Admin Delete a contacts list. ### `POST /contacts_lists/{contacts_list_id}/contacts/{contact_id}` Admin Add a contact to the contacts list. ### `DELETE /contacts_lists/{contacts_list_id}/contacts/{contact_id}` Admin Remove a contact from the contacts list. ### `POST /accounts/{id}/contacts_lists/{contacts_list_id}` Admin Add a contacts list to the account. ### `DELETE /accounts/{id}/contacts_lists/{contacts_list_id}` Admin Remove a contacts list from the account. ## 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: * `key` **required**, alpha numeric with dashes, lowercase ### `PUT /account_types/{id}` Admin Update an account type. JSON parameters: * `key` **required**, alpha numeric with dashes, lowercase ### `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 type from the account. ## Messages ### `POST /messages` Admin Send a message over SIP. JSON parameters: * `to` **required**, SIP address of the receiver * `body` **required**, content of the message ## Push Notifications ### `POST /push_notification` User Send a push notification using the Flexisip Pusher. JSON parameters: * `pn_provider` **required**, the push notification provider, must be in `apns.dev`, `apns` or `fcm` * `pn_param` the push notification parameter, can be null or contain only alphanumeric and underscore characters * `pn_prid` the push notification unique id, can be null or contain only alphanumeric, dashes, underscore and colon characters * `type` **required**, must be in `background`, `message` or `call` * `call_id` a Call ID, must have only alphanumeric, tilde and dashes characters ## Phone Countries The phone numbers managed by FlexiAPI are validated against a list of countries that can be managed in the admin web panels. ### `GET /phones_countries` Public Return the list of Phone Countries and their current status. If a country is deactivated all the new submitted phones submitted on the platform will be blocked. ## Statistics FlexiAPI can record logs generated by the FlexiSIP server and compile them into statistics. ### `POST /statistics/messages` Admin Announce the creation of a message. JSON parameters: * `id` **required**, string * `from` **required**, string the sender of the message * `sent_at` **required**, string, format ISO8601, when the message was actually sent * `encrypted` **required**, boolean * `conference_id` string ### `PATCH /statistics/messages/{message_id}/to/{to}/devices/{device_id}` Admin Complete a message status. JSON parameters: * `last_status` **required**, an integer containing the last status code * `received_at` **required**, format ISO8601, when the message was received ### `POST /statistics/calls` Admin Announce the beginning of a call. JSON parameters: * `id` **required**, string * `from` **required**, string the initier of the call * `to` **required**, string the destination of the call * `initiated_at` **required**, string, format ISO8601, when the call was started * `ended_at` string, format ISO8601, when the call finished * `conference_id` string ### `PATCH /statistics/calls/{call_id}/devices/{device_id}` Admin Complete a call status. JSON parameters: * `rang_at` format ISO8601, when the device rang * `invite_terminated` * `at` format ISO8601, when the invitation ended * `state` the termination state ### `PATCH /statistics/calls/{call_id}` Admin Update a call when ending. JSON parameters: * `ended_at` **required**, string, format ISO8601, when the call finished # 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. ## Contacts list ### `GET /contacts/vcard` User Return the authenticated user contacts list, in [vCard 4.0 format](https://datatracker.ietf.org/doc/html/rfc6350). 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](https://datatracker.ietf.org/doc/html/rfc6350). ## vCards Storage ### `GET /vcards-storage` User Return the list of stored vCards ### `GET /vcards-storage/{uuid}` User Return a stored vCard