mirror of
https://gitlab.linphone.org/BC/public/flexisip-account-manager.git
synced 2026-01-17 10:08:05 +00:00
200 lines
6.3 KiB
PHP
200 lines
6.3 KiB
PHP
# About
|
|
|
|
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]({{ route('account.login') }}) 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.<br />
|
|
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](https://tools.ietf.org/html/rfc7616).
|
|
|
|
# Endpoints
|
|
|
|
## Public endpoints
|
|
|
|
### General
|
|
|
|
#### `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.
|
|
|
|
### Accounts
|
|
|
|
#### `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
|
|
|
|
### Accounts 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
|
|
|
|
### Accounts 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.
|
|
|
|
### Accounts
|
|
|
|
#### `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` **not configurable** the value is enforced to the default registration domain set in the global configuration
|
|
* `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.
|
|
|
|
# Provisioning
|
|
|
|
When an account is having an available `confirmation_key` it can be provisioned using the two following URL.
|
|
|
|
Those two URL are <b>not API endpoints</b>, they are not located under `/api`.
|
|
|
|
### `VISIT /provisioning/{confirmation_key}`
|
|
Return the provisioning information available in the liblinphone configuration file (if correctly configured).
|
|
If the `confirmation_key` 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.
|
|
|
|
### `VISIT /provisioning/qrcode/{confirmation_key}`
|
|
Return a QRCode that points to the provisioning URL.
|