Token

A token allows us to link a user (whether he is registered or not) to any data we have stored about that user. This data can be customer-information, shoppingcart-information and so on..

The token resource offers the following methods:

1 Get token
2 Check token
3 Refresh token

Before making any requests to the MediaServices API, you should obtain a token. This token provides you with a temporary, secure access to the API and should be used in any request you make. Only a few webservices don't need a token when called (e.g. Search ).

Good practice is to get or retrieve (e.g. from a cookie) a token at the moment a user enters the website.

Requesting a token for a customer that already has a token should be avoided, as he will be considered a guest user.

Authentication

When you log a user in, via the Authentication webservice, their token (initially a guest token) and customerID are bound together. That's how authentication is made.

Expiration and tokens

Tokens are bound to users, and users have accreditation levels. Depending on the user's role, tokens are valid for a certain period (up to a month for registered users). We recommend you store them somewhere on the client's side (e.g. in cookies) and re-use it until its expiration date has passed or the token is refreshed.

When you get a token for a user, our service will communicate an expiration date and a refresh token.

By calling the Refresh webservice, you can request a new token by passing the old token (e.g. when the token is about to expire). The service will return a new token with a fresh lifespan. If you replace the old token by the new token, than the user won't have log in again.

A token will be removed in case of a logout or if it's expiration lifespan has passed.

Get token

That's how you get a token.

Example

https://wsmedia.tlsecure.com/api/json/00000/customer/token

Request

HTTP Verb : GET
URL : http://{WS_URL}/api/{returnType}/{domainCode}/customer/token

Response

Success

{
     "response":{
          "success":true,
          "message":"token retrieving",
          "object":{
               "token":{
                    "value":"s75o0md86dhq3f0sia3ce3t9lb",
                    "customer":640,
                    "expirationDate":"2016-03-08 15:28:56",
                    "refresh":"uonqvuumbol0k7eqbv93rl353t"
                    }
               }
          }
     }
}

Error

{
     "response":{
          "success":false,
          "code":10,
          "message":"token provided in the request"
     }
}

Codelist

code	success	message

code	success	message
0	v	token given
1		domaincode malformed
2		connection error
10		token provided in the request
99		uncatched exception

Check token

Shares the same HTTP-method (GET) as the Get token-webservice, but this webservice requires a token to be passed as a parameter.

Check if a token is valid AND retrieve the user basic information (login, email, shopping cart).

This webservice isn't designed to be called before making any other requests : the token is checked in each webservice.

It does provides an easy way to:

check if a user is connected as he comes on your website
retrieve basic info which can be displayed (name, amount of products) on the website without needing to call many others webservices.

Example

https://wsmedia.tlsecure.com/api/json/00000/customer/token/check

Request

HTTP Verb : GET
URL : http://{WS_URL}/api/{returnType}/{domainCode}/customer/token/check

Parameters	Location	Type	Required	Default	Accepted

Parameters	Location	Type	Required	Default	Accepted
token	Header	String(26)	v

Response

Success

{
	"response": {
		"success": true
		"message": "valid token"
		"object": {
			"cart": {
				"customer": 4
				"price": 22.5
				"totalPrice": 22.5
				"creationDate": "2016-02-29 15:18:34"
				"lines": {
					"line": [1]
						0:  {
							"id": 1
							"ean": 9789462500877
							"title": "Kip"
							"author": "Marcus Bean & Ellen Hosmar"
							"price": 22.5
							"quantity": 1
							"productForm": "BB"
						}
				}
			}
			"customer": {
				"id": 4
				"role": 1
				"email": "bbanner@avengers.com"
				"login": "bbanner"
				"b2b": false
				"newsletter": true
				"creationDate": "2016-03-01"
				"waitingEmailValidation": false
			}
			"token": {
				"value": "fj3gdebhjacm0ufv72sinfme1d"
				"customer": 4
				"expirationDate": "2016-03-31 16:03:47"
				"refresh": "hf0e0jljs6drf926nu5d9ul1k9"
			}
		}
	}
}

In case of an unregistered user, the response will not contain any customer- or token object.

Error

Codelist

Code	Success	Message

Code	Success	Message
0	v	valid token
1		domaincode malformed
2		connection error
3		token empty
4		no token with that key
5		invalid token
10		invalid token
99		uncatched exception

Refresh token

If a token comes to expire, you can update it with a new one.

This can be done by passing the current token and the refresh token to this webservice. The service will respond with a new token, with a prolonged duration.

Example

https://wsmedia.tlsecure.com/api/json/00000/customer/token

Request

HTTP Verb : PUT
URL : http://{WS_URL}/api/{returnType}/{domainCode}/customer/token

Parameters	Location	Type	Required	Default	Accepted

Parameters	Location	Type	Required	Default
token	Header	String(26)	v
Content-Type	Header	String	v	application/x-www-form-urlencoded
refresh	Form	String(26)	v

Response

Success

Error

Codelist

Code	Success	Message

Code	Success	Message
0	v	token refreshed
1		domaincode malformed
2		connection error
3		token empty
4		no token with that key
5		invalid token
9		{param} not {type} {(or undefined)}
10		unmatching refresh token
99		uncatched exception

MediaWeb WebServices

Token

Authentication

Expiration and tokens

Get token

Example

Request

Response

Success

Error

Codelist

Check token

Example

Request

Response

Success

Error

Codelist

Refresh token

Example

Request

Response

Success

Error

Codelist

Related content