Share the following picture with the user or the one-time-use link bellow.
-
+
The following link can only be visited once
-
+
Renew the provision link
The current one will be unavailable
diff --git a/flexiapi/resources/views/api/documentation_markdown.blade.php b/flexiapi/resources/views/api/documentation_markdown.blade.php
index d96ba0b..51cd6f6 100644
--- a/flexiapi/resources/views/api/documentation_markdown.blade.php
+++ b/flexiapi/resources/views/api/documentation_markdown.blade.php
@@ -17,6 +17,14 @@ A `from` (consisting of the user SIP address, prefixed with `sip:`), `content-ty
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
+
## Using the API Key
You can retrieve an API Key from @if (config('app.web_panel')) [your account panel]({{ route('account.login') }}) @else your account panel @endif or using the dedicated API endpoint.
@@ -59,17 +67,19 @@ You can find more documentation on the related [IETF RFC-7616](https://tools.iet
# Endpoints
-## Public endpoints
+## Ping
-### General
-
-#### `GET /ping`
+### `GET /ping`
+Public
Returns `pong`
-### Accounts
+## Account Creation Tokens
-#### `POST /tokens`
-Send a token using a push notification to the device.
+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.
@@ -79,8 +89,16 @@ JSON parameters:
* `pn_param` the push notification parameter
* `pn_prid` the push notification unique id
-#### `POST /accounts/with-token`
-Create an account using a token.
+### `POST /account_creation_tokens`
+Admin
+
+Create and return an `account_creation_token`.
+
+## 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.
JSON parameters:
@@ -89,49 +107,52 @@ JSON parameters:
* `password` required minimum 6 characters
* `algorithm` required, values can be `SHA-256` or `MD5`
* `domain` **not configurable except during test deployments** the value is enforced to the default registration domain set in the global configuration
-* `token` the unique token
+* `account_creation_token` the unique `account_creation_token`
* `dtmf_protocol` optional, values must be `sipinfo` or `rfc2833`
-#### `GET /accounts/{sip}/info`
+### `GET /accounts/{sip}/info`
+Public
Retrieve public information about the account.
Return `404` if the account doesn't exists.
-#### `POST /accounts/{sip}/activate/email`
+### `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:
* `code` the code
-#### `POST /accounts/{sip}/activate/phone`
+### `POST /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:
* `code` the PIN code
-## User authenticated endpoints
-Those endpoints are authenticated and requires an activated account.
-
-### Accounts
-
-#### `GET /accounts/me/api_key`
+### `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`
+### `GET /accounts/me`
+User
Retrieve the account information.
-#### `DELETE /accounts/me`
+### `DELETE /accounts/me`
+User
Delete the account.
-#### `POST /accounts/me/email/request`
+### `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
-#### `POST /accounts/me/password`
+### `POST /accounts/me/password`
+User
Change the account password.
JSON parameters:
@@ -139,47 +160,10 @@ JSON parameters:
* `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.
-
-### Accounts contacts
-
-#### `GET /accounts/me/contacts`
-Return the user contacts.
-
-#### `GET /accounts/me/contacts/{sip}`
-Return a user contact.
-
-## Admin endpoints
-
-Those endpoints are authenticated and requires an admin account.
-
-### Accounts
-
-#### `POST /accounts`
+### `POST /accounts`
+Admin
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`.
+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:
@@ -195,49 +179,100 @@ The `domain` field is taken into account ONLY when `app.admins_manage_multi_doma
* `dtmf_protocol` optional, values must be `sipinfo` 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`.
-#### `GET /accounts`
+### `GET /accounts`
+Admin
Retrieve all the accounts, paginated.
-#### `GET /accounts/{id}`
+### `GET /accounts/{id}`
+Admin
Retrieve a specific account.
-#### `GET /accounts/{sip}/search`
+### `GET /accounts/{sip}/search`
+Admin
Search for a specific account by sip address.
-#### `DELETE /accounts/{id}`
+### `DELETE /accounts/{id}`
+Admin
Delete a specific account and its related information.
-#### `GET /accounts/{id}/activate`
+### `GET /accounts/{id}/activate`
+Admin
Activate an account.
-#### `GET /accounts/{id}/deactivate`
+### `GET /accounts/{id}/deactivate`
+Admin
Deactivate an account.
-#### `GET /accounts/{id}/provision`
-Re-provision an account by generating a fresh `confirmation_key`.
+### `GET /accounts/{id}/provision`
+Admin
+Re-provision an account by generating a fresh `provisioning_token`.
-### Contacts
+## Accounts phone number
-#### `GET /accounts/{id}/contacts/`
+### `POST /accounts/me/phone/request`
+User
+Request a specific code by SMS
+JSON parameters:
+
+* `phone` the phone number to send the SMS
+
+### `POST /accounts/me/phone`
+User
+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`
+User
+Return the user registered devices.
+
+### `DELETE /accounts/me/devices/{uuid}`
+User
+Remove one of the user registered devices.
+
+## Accounts contacts
+
+### `GET /accounts/me/contacts`
+User
+Return the user contacts.
+
+### `GET /accounts/me/contacts/{sip}`
+User
+Return a user contact.
+
+## Contacts
+
+### `GET /accounts/{id}/contacts/`
+Admin
Get all the account contacts.
-#### `POST /accounts/{id}/contacts/{contact_id}`
+### `POST /accounts/{id}/contacts/{contact_id}`
+Admin
Add a contact to the list.
-#### `DELETE /accounts/{id}/contacts/{contact_id}`
+### `DELETE /accounts/{id}/contacts/{contact_id}`
+Admin
Remove a contact from the list.
-### Account Actions
+## Account Actions
The following endpoints will return `403 Forbidden` if the requested account doesn't have a DTMF protocol configured.
-#### `GET /accounts/{id}/actions/`
+### `GET /accounts/{id}/actions/`
+Admin
Show an account related actions.
-#### `GET /accounts/{id}/actions/{action_id}`
+### `GET /accounts/{id}/actions/{action_id}`
+Admin
Show an account related action.
-#### `POST /accounts/{id}/actions/`
+### `POST /accounts/{id}/actions/`
+Admin
Create an account action.
JSON parameters:
@@ -245,7 +280,8 @@ JSON parameters:
* `key` required, alpha numeric with dashes, lowercase
* `code` required, alpha numeric, lowercase
-#### `PUT /accounts/{id}/actions/{action_id}`
+### `PUT /accounts/{id}/actions/{action_id}`
+Admin
Create an account action.
JSON parameters:
@@ -253,43 +289,52 @@ JSON parameters:
* `key` required, alpha numeric with dashes, lowercase
* `code` required, alpha numeric, lowercase
-#### `DELETE /accounts/{id}/actions/{action_id}`
+### `DELETE /accounts/{id}/actions/{action_id}`
+Admin
Delete an account related action.
-### Account Types
+## Account Types
-#### `GET /account_types/`
+### `GET /account_types/`
+Admin
Show all the account types.
-#### `GET /account_types/{id}`
+### `GET /account_types/{id}`
+Admin
Show an account type.
-#### `POST /account_types/`
+### `POST /account_types/`
+Admin
Create an account type.
JSON parameters:
* `key` required, alpha numeric with dashes, lowercase
-#### `PUT /account_types/{id}`
+### `PUT /account_types/{id}`
+Admin
Update an account type.
JSON parameters:
* `key` required, alpha numeric with dashes, lowercase
-#### `DELETE /account_types/{id}`
+### `DELETE /account_types/{id}`
+Admin
Delete an account type.
-#### `POST /accounts/{id}/types/{type_id}`
+### `POST /accounts/{id}/types/{type_id}`
+Admin
Add a type to the account.
-#### `DELETE /accounts/{id}/contacts/{type_id}`
+### `DELETE /accounts/{id}/contacts/{type_id}`
+Admin
Remove a a type from the account.
-### Messages
+## Messages
-#### `POST /messages`
+### `POST /messages`
+Admin
Send a message over SIP.
JSON parameters:
@@ -297,15 +342,18 @@ JSON parameters:
* `to` required, SIP address of the receiver
* `body` required, content of the message
-### Statistics
+## Statistics
-#### `GET /statistics/day`
+### `GET /statistics/day`
+Admin
Retrieve registrations statistics for 24 hours.
-#### `GET /statistics/week`
+### `GET /statistics/week`
+Admin
Retrieve registrations statistics for a week.
-#### `GET /statistics/month`
+### `GET /statistics/month`
+Admin
Retrieve registrations statistics for a month.
# Non-API Endpoints
@@ -314,28 +362,31 @@ The following URLs are **not API endpoints** they are not returning `JSON` conte
## Provisioning
-When an account is having an available `confirmation_key` it can be provisioned using the two following URL.
+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/{confirmation_key}`
+### `GET /provisioning/{provisioning_token}`
+Public
Return the provisioning information available in the liblinphone configuration file.
-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 (the content will be the same as the previous url).
+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 `confirmation_key` is valid. The account will be activated.
+If the account is not activated and the `provisioning_token` is valid. The account will be activated.
-### `GET /provisioning/qrcode/{confirmation_key}`
+### `GET /provisioning/qrcode/{provisioning_token}`
+Public
Return a QRCode that points to the provisioning URL.
-## Authenticated provisioning
-
### `GET /provisioning/me`
-Return the same base content as the previous URL and the account related information, similar to the `confirmation_key` endpoint. However this endpoint will always return those information.
+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.
-## Authenticated contact list
+## 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:
@@ -360,4 +411,5 @@ Here is the format of the vCard list returned by the endpoint:
```
### `GET /contacts/vcard/{sip}`
+User
Return a specific user authenticated contact, in [vCard 4.0 format](https://datatracker.ietf.org/doc/html/rfc6350).
\ No newline at end of file
diff --git a/flexiapi/routes/api.php b/flexiapi/routes/api.php
index 7016edd..8251e2e 100644
--- a/flexiapi/routes/api.php
+++ b/flexiapi/routes/api.php
@@ -26,9 +26,9 @@ Route::middleware('auth:api')->get('/user', function (Request $request) {
});
Route::get('ping', 'Api\PingController@ping');
-Route::post('tokens', 'Api\TokenController@create');
+Route::post('account_creation_tokens/send-by-push', 'Api\AccountCreationTokenController@sendByPush');
Route::get('accounts/{sip}/info', 'Api\AccountController@info');
-Route::post('accounts/with-token', 'Api\AccountController@store');
+Route::post('accounts/with-account-creation-token', 'Api\AccountController@store');
Route::post('accounts/{sip}/activate/email', 'Api\AccountController@activateEmail');
Route::post('accounts/{sip}/activate/phone', 'Api\AccountController@activatePhone');
diff --git a/flexiapi/routes/web.php b/flexiapi/routes/web.php
index 9a59f02..1ab68db 100644
--- a/flexiapi/routes/web.php
+++ b/flexiapi/routes/web.php
@@ -42,8 +42,8 @@ Route::group(['middleware' => 'auth.digest_or_key'], function () {
Route::get('contacts/vcard', 'Account\ContactVcardController@index')->name('account.contacts.vcard.index');
});
-Route::get('provisioning/qrcode/{confirmation}', 'Account\ProvisioningController@qrcode')->name('provisioning.qrcode');
-Route::get('provisioning/{confirmation?}', 'Account\ProvisioningController@show')->name('provisioning.show');
+Route::get('provisioning/qrcode/{provisioning_token}', 'Account\ProvisioningController@qrcode')->name('provisioning.qrcode');
+Route::get('provisioning/{provisioning_token?}', 'Account\ProvisioningController@show')->name('provisioning.show');
if (config('app.public_registration')) {
if (config('app.phone_authentication')) {
diff --git a/flexiapi/tests/Feature/AccountApiTest.php b/flexiapi/tests/Feature/AccountApiTest.php
index d778769..d305313 100644
--- a/flexiapi/tests/Feature/AccountApiTest.php
+++ b/flexiapi/tests/Feature/AccountApiTest.php
@@ -140,6 +140,7 @@ class AccountApiTest extends TestCase
]);
$this->assertFalse(empty($response1['confirmation_key']));
+ $this->assertFalse(empty($response1['provisioning_token']));
}
public function testAdminMultiDomains()
@@ -235,6 +236,7 @@ class AccountApiTest extends TestCase
]);
$this->assertFalse(empty($response1['confirmation_key']));
+ $this->assertFalse(empty($response1['provisioning_token']));
}
public function testUsernameNoDomain()
@@ -305,6 +307,7 @@ class AccountApiTest extends TestCase
]);
$this->assertTrue(!empty($response1['confirmation_key']));
+ $this->assertFalse(empty($response1['provisioning_token']));
}
public function testActivated()
@@ -334,6 +337,7 @@ class AccountApiTest extends TestCase
]);
$this->assertTrue(empty($response1['confirmation_key']));
+ $this->assertTrue(empty($response1['provisioning_token']));
}
public function testNotActivated()
@@ -362,6 +366,7 @@ class AccountApiTest extends TestCase
]);
$this->assertFalse(empty($response1['confirmation_key']));
+ $this->assertFalse(empty($response1['provisioning_token']));
}
public function testSimpleAccount()
diff --git a/flexiapi/tests/Feature/AccountTokenTest.php b/flexiapi/tests/Feature/AccountCreationTokenTest.php
similarity index 83%
rename from flexiapi/tests/Feature/AccountTokenTest.php
rename to flexiapi/tests/Feature/AccountCreationTokenTest.php
index bfb16ea..909075b 100644
--- a/flexiapi/tests/Feature/AccountTokenTest.php
+++ b/flexiapi/tests/Feature/AccountCreationTokenTest.php
@@ -22,14 +22,14 @@ namespace Tests\Feature;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
-use App\Token;
+use App\AccountCreationToken;
-class AccountTokenTest extends TestCase
+class AccountCreationTokenTest extends TestCase
{
use RefreshDatabase;
- protected $tokenRoute = '/api/tokens';
- protected $accountRoute = '/api/accounts/with-token';
+ protected $tokenRoute = '/api/account_creation_tokens/send-by-push';
+ protected $accountRoute = '/api/accounts/with-account-creation-token';
protected $method = 'POST';
protected $pnProvider = 'provider';
@@ -54,7 +54,7 @@ class AccountTokenTest extends TestCase
public function testLimit()
{
- $token = Token::factory()->create();
+ $token = AccountCreationToken::factory()->create();
$response = $this->json($this->method, $this->tokenRoute, [
'pn_provider' => $token->pn_provider,
@@ -66,14 +66,14 @@ class AccountTokenTest extends TestCase
public function testInvalidToken()
{
- $token = Token::factory()->create();
+ $token = AccountCreationToken::factory()->create();
// Invalid token
$response = $this->json($this->method, $this->accountRoute, [
'username' => 'username',
'algorithm' => 'SHA-256',
'password' => '2',
- 'token' => '0123456789abc'
+ 'account_creation_token' => '0123456789abc'
]);
$response->assertStatus(422);
@@ -82,7 +82,7 @@ class AccountTokenTest extends TestCase
'username' => 'username',
'algorithm' => 'SHA-256',
'password' => '2',
- 'token' => $token->token
+ 'account_creation_token' => $token->token
]);
$response->assertStatus(200);
@@ -91,7 +91,7 @@ class AccountTokenTest extends TestCase
'username' => 'username2',
'algorithm' => 'SHA-256',
'password' => '2',
- 'token' => $token->token
+ 'account_creation_token' => $token->token
]);
$response->assertStatus(422);
}
diff --git a/flexiapi/tests/Feature/AccountProvisioningTest.php b/flexiapi/tests/Feature/AccountProvisioningTest.php
index 043f0d7..a8f5688 100644
--- a/flexiapi/tests/Feature/AccountProvisioningTest.php
+++ b/flexiapi/tests/Feature/AccountProvisioningTest.php
@@ -83,7 +83,7 @@ class AccountProvisioningTest extends TestCase
$password->account->save();
// Ensure that we get the authentication password once
- $response = $this->get($this->route.'/'.$password->account->confirmation_key)
+ $response = $this->get($this->route.'/'.$password->account->provisioning_token)
->assertStatus(200)
->assertHeader('Content-Type', 'application/xml')
->assertSee('ha1');
@@ -92,31 +92,31 @@ class AccountProvisioningTest extends TestCase
$this->assertEquals(true, DBAccount::where('id', $password->account->id)->first()->activated);
// And then twice
- $response = $this->get($this->route.'/'.$password->account->confirmation_key)
+ $response = $this->get($this->route.'/'.$password->account->provisioning_token)
->assertStatus(200)
->assertHeader('Content-Type', 'application/xml')
->assertDontSee('ha1');
$password->account->refresh();
- $confirmationKey = $password->account->confirmation_key;
+ $provisioningToken = $password->account->provisioning_token;
- // Refresh the confirmation_key
+ // Refresh the provisioning_token
$admin = Admin::factory()->create();
$admin->account->generateApiKey();
$this->keyAuthenticated($admin->account)
->json($this->method, '/api/accounts/'.$password->account->id.'/provision')
->assertStatus(200)
- ->assertSee('confirmation_key')
- ->assertDontSee($confirmationKey);
+ ->assertSee('provisioning_token')
+ ->assertDontSee($provisioningToken);
$password->account->refresh();
- $this->assertNotEquals($confirmationKey, $password->account->confirmation_key);
+ $this->assertNotEquals($provisioningToken, $password->account->provisioning_token);
// And then provision one last time
- $this->get($this->route.'/'.$password->account->confirmation_key)
+ $this->get($this->route.'/'.$password->account->provisioning_token)
->assertStatus(200)
->assertHeader('Content-Type', 'application/xml')
->assertSee('ha1');
diff --git a/flexisip-account-manager.spec b/flexisip-account-manager.spec
index 0df9f8c..ddacd82 100644
--- a/flexisip-account-manager.spec
+++ b/flexisip-account-manager.spec
@@ -8,7 +8,7 @@
#%define _datadir %{_datarootdir}
#%define _docdir %{_datadir}/doc
-%define build_number 137
+%define build_number 138
%define var_dir /var/opt/belledonne-communications
%define opt_dir /opt/belledonne-communications/share/flexisip-account-manager