The authentication of a client to access the VeBox API uses OAuth 2.0.
It uses the Password grant for logging in with the user's username and password.
To login with the user credentials and obtain a token, a request is made using POST to the following resource:
/oauth/token.
Content-Type: application/x-www-form-urlencoded.
The request header must have a Basic Authentication with the client id and secret as username and password.
The request body supports the following fields:
grant_type: The grant type. Must be always password.username: The username of the user.password: The password of the user.
A successful request will return the token for the user.
access_token: The access token that need to be added at each API request to authenticate.token_type: The token type. Always bearer.refresh_token: The refresh token used to obtain a new access token if it expires.scope: The scope of the client. Currently always mobile.
To refresh a token, a request is made using POST to the following resource:
/oauth/token.
Content-Type: application/x-www-form-urlencoded.
The request header must have a Basic Authentication with the client id and secret as username and password.
The request body supports the following fields:
grant_type: The grant type. Must be always refresh_token.refresh_token: The refresh token obtained in the previous token retrieval.
A successful request will return a new token with the same structure of the token obtained the first time.
It is possible to check if an access token is valid with a GET or POST request to the following resource:
/oauth/check_token.
The request body supports the following fields:
token: The access token to check.
A successful request will return the information about the scope, resource ids, authorities, ecc...
aud: The resource ids. Currently always vebox.user_name: The username of the user.authorities: An array of strings with the user permissions.client_id: The id of the client.scope: An array of strings with the scopes. Currently always mobile.
To retrieve the user information, a request is made using GET to the following resource:
/user.
The request body supports the following fields:
access_token: The access token used to authenticate.
A successful request will return the information about the user.
name: The name of the user.surname: The surname of the user.email: The email of the user. Can be null.company: The company name of the user.locale: The locale of the user.timezone: The timezone of the user.