Authentication
- Jasper Verfaillie
As a REST API, we're stateless. That means the we don't deal with sessions. Therefore each request to our services implicate that the user must be validated. Instead of log them in on each time, we use Tokens.
However, an authentication is needed for the large part of the services. That's done with the Login Webservice, which binds the token that the user use, with its information (customersID) in our database. So that's not really a real login, but a token accreditation based on the customer credentials.
We also provide a Logoff Webservice. That's nothing more than a token invalidation. That shouldn't be used in regular cases.
Login
Example
Request
HTTP Verb : GET
URL : http://{WS_URL}/api/{returnType}/{domainCode}/customer/login
Parameters | Location | Type | Required | Default | Accepted |
|---|---|---|---|---|---|
token | Header | String(26) | v |
|
|
login | Query | string | v |
|
|
password | Query | string | v |
| encrypted |
The password provided have to be encrypted and salted. Ask us directly for the encryption algorithm.
Response
Success
{
"response": {
"success": true
"message": "login successfull"
"object": {
"customer": {
"id": 586
"role": 1
"email": "spiderman@avengers.com"
"login": "spiderman"
"b2b": false
"newsletter": false
"creationDate": "2016-03-01"
"waitingEmailValidation": false
}
"token": {
"value": "k368uulrnlpr7d2n0j59spueeq"
"customer": 586
"expirationDate": "2016-04-01 10:37:02"
"refresh": "c8skottai6bhpufnk6tqa6i2hq"
}
}
}
}Error
{
"response": {
"success": false,
"code": 11,
"message": "wrong password"
}
}Codelist
Code | Success | Message |
|---|---|---|
0 | v | login successfull |
1 |
| domaincode malformed |
2 |
| connexion error |
3 |
| token is empty |
4 |
| no token with that key |
5 |
| invalid token |
9 |
| {param} is not {type} {(or undefined)} |
10 |
| already logged in |
11 |
| wrong password |
12 |
| user not exist |
99 |
| uncatched exception |
Logout
Example
https://wsmedia.tlsecure.com/api/json/00000/customer/logout
Request
HTTP Verb : GET
URL : http://{WS_URL}/api/{returnType}/{domainCode}/customer/logout
Parameters | Location | Type | Required | Default | Accepted |
|---|---|---|---|---|---|
token | Header | String(26) | v |
|
|
Token will be invalidated as you log out. Thus you'll have to ask for a new one
Response
Success
{
"response": {
"success": true
"code": 0
"message": "logoff successfull"
}
}Error
Codelist
Code | Success | Message |
|---|---|---|
0 | v | logoff successfull |
1 |
| domaincode malformed |
2 |
| connexion error |
3 |
| Token is empty |
4 |
| No token with that key |
5 |
| Invalid token |
10 |
| Not logged in |
99 |
| Uncatched exception |
Lost password
See here for the complete procedure.
Customer validation (after registration)
This is the service that will have to be called after a customer clicks on the link he got in the subscription mail. See the customer creation for more information.
That's a required step to validate it ; else he won't be able to login, throwing a “user not confirmed by email” error.
Example
Request
HTTP Verb : GET
URL : http://{WS_URL}/api/{returnType}/{domainCode}/customer/validate
Parameters | Location | Type | Required | Default | Accepted |
|---|---|---|---|---|---|
token | Header | String(26) |
|
|
|
user | Query | long | v |
| customerID |
validationKey | Query | String(26) | v |
| validation key |
The token isn't required. But if it's provided at this step, and it doesn't belong to a registred customer, the current one will be authenticated automatically.
Response
Success - NO token
Success - WITH token
Error
Codelist
Code | Success | Message |
|
|---|---|---|---|
0 | v | user validated |
|
1 |
| domaincode malformed |
|
2 |
| connexion error |
|
3 |
| token empty | only if token provided |
4 |
| no token with that key | only if token provided |
5 |
| invalid token | only if token provided |
9 |
| {param} not {type} {(or undefined)} |
|
10 |
| user not exist |
|
11 |
| user already validated |
|
12 |
| validation key not match |
|
99 |
| uncatched exception |
|