# 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>