mirror of
https://gitlab.linphone.org/BC/public/flexisip-account-manager.git
synced 2026-01-17 10:08:05 +00:00
115 lines
3.5 KiB
PHP
115 lines
3.5 KiB
PHP
# 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
|
|
```
|
|
|
|
<div class="card">
|
|
|
|
Restricted endpoints are protected using a DIGEST authentication or an API Key mechanisms.
|
|
|
|
### Access model
|
|
|
|
The endpoints are accessible using three different models:
|
|
|
|
- <span class="badge badge-success">Public</span> publicly accessible
|
|
- <span class="badge badge-info">User</span> the endpoint can only be accessed by an authenticated user
|
|
- <span class="badge badge-warning">Admin</span> the endpoint can be only be accessed by an authenticated admin user
|
|
- <span class="badge badge-error">Super Admin</span> the endpoint can be only be accessed by an authenticated super admin user
|
|
|
|
### Space expiration
|
|
|
|
<span class="badge badge-error">Super Admin</span> 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 <a href="#get-accountsmeapikey">the dedicated API endpoint</a>.
|
|
|
|
**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 <a href="https://jwt.io/">JWT</a> 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.<br />
|
|
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).
|
|
|
|
</div>
|