Getting the authorization token using OAuth2

All the API methods require authorization.
The information below describes the steps to get an authorization token and the usage of the token to authorize for API methods.

POST /Token

Request Information

Header Parameters

Authorization: Basic [base64 encoding of {client_id}:{client_secret}]
Note: the string {client_id}:{client_secret} should be Base64 encoded.

NameValue
client_id test_user
client_secret test_secret
test_user:test_secret in base64 dGVzdF91c2VyOnRlc3Rfc2VjcmV0
Resulting header Authorization: Basic dGVzdF91c2VyOnRlc3Rfc2VjcmV0

URI Parameters

None.

Body Parameters

NameTypeDescription
grant_type String Type of grant required. Use “password”.
username String The username in the application.
password String The password in the application.

Request Format

application/x-www-form-urlencoded

POST https://api.cloud.materialise.com/Token HTTP/1.1
Authorization: Basic zXdtLXNlcnZpY2U6MhkyOTA0RUItNjg2My00ODhyLTk1OEItMUMzQjI0OTVBM0I4
Content-Type: application/x-www-form-urlencoded
Host: api.cloud.materialise.com

grant_type=password&username=test@test.com&password=my_password

Response Information

Response Format

application/json

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 851
Content-Type: application/json;charset=UTF-8
Expires: -1
Date: Thu, 30 Jul 2015 09:05:54 GMT

{"access_token":"Eye8dHrbdJGPkfOf0AyHEoR5mWoa-JJTjFt5XqGQL5s3wbG6ghks7QrcgFVH8tTwo7WlSRjOJBqm6ogqy49O_SB3FnjTCc1SS6pD4r3kYGh96O3u1kaWNBFvdVYJG3Aw89sOCGQOaB_zJsJGfXjYxpeNUVbVDvmGDEmmoCrpoyObz2kPHBpfIlCkQtDCew280HErrlqZz-EB6EygRb4AZ0Ri5ODT5jn8ZSDH5PlUPTtHVWZRmIODqABHPxDSAPWa5_-LD96BQxZhmYtNTc3GBSRifvxi29-_2J5E5yU1MCfHr9dytmQEBNMXf3ckLalmbD34wmYgNPr8O_pM__LPHe9ymy03RYeNXDCi2uvUhRtFAMfj0-OR8_O-Zuxf1aRUz3zqRCgayqymuWduRwFHeouWoFmlK5BBGtCknBA6NDarZ0gimnEDld7o6AShZR2ZFzBnnMRXTFH1mu-Lfre1TW0BfUwpNFDo-49itELxXcgerGsok61yIsaxVKQ-uf5NWw0m29TnkZB5nSyxOtyJ_ZVKBoSbtMWbLNGAh0S6uJLSDZTwY2gqgxPAcxAFbyBSxhl1Fg",
"token_type":"bearer",
"expires_in":899,
"refresh_token":"a5beac8430c64d81aa3282c9f19a183e",
"userName":"25bbc91c-a4ac-4877-b5a0-0aad9deb34c0",
"as:client_id":"apitest",
".issued":"Thu, 30 Jul 2015 09:05:49 GMT",
".expires":"Thu, 30 Jul 2015 09:20:49 GMT"}

Using the authorization token

To use the authorization token from the previous chapter, add an Authorization header to your API requests in the following format:
Authorization: Bearer {token}

Sample

multipart/form-data

POST https://api.cloud.materialise.com/web-api/operation/file HTTP/1.1
Authorization: Bearer TJHid1LfbdxsVD48mB7nwMr4fQhrKY9eEmPhF-ZUGs4idTYrR5yRgEllLcBA1JpOUgb4DZ6tQVgh-bjxwR_PxubNLEtuCDOoB2t_X1RdTObOerzugNezPsRpnSXQC3ytCnnBeNxkd58nHeFVtvsw5U3ni7uayUHY8_tpR14ldM6LNFDTpOL_2fYU2gyGGFXxBgQuz4v5_0MYSwpUQQJ_kIM9S2wZstZi8guqDcPzJRWspJeYoqPVar__g30SAi-90j4vbmq9hWbT4XwdkGeXjztkV6XnnPaSXtR-73kl58BgjAHOCNj0P6oQLYVMSDT7GCtASHH62k30D7c7Ku3nmFPZYnrEACycOhnYtaNVCoTekBi8GqiaESRwAvzMTy0GggoMs78HXbPBnivOMI_PdxQRnxGT4zGxHhGvOgDVnYRJ9BqNBcqc6SCMytjfdY-4sSoM4uUzILrqX15QQ5JK_RteIHbdX_7TfDeW_JEVGPxAS9BSdNKU0IwAqj4NdHzuEBafkA
Content-Type: multipart/form-data; boundary=-------------------------acebdf13572468

---------------------------acebdf13572468
Content-Disposition: form-data; name="fieldNameHere"; filename="Plug.stl"
Content-Type: application/vnd.ms-pki.stl

Getting the Refresh token using OAuth2

The authorization token is short lived (default: 15 minutes) for security reasons. To make a new API request you may either get a new authorization token or use a refresh token.
A refresh token is usually long lived (default: 2 months) and doesn’t require a user’s password. Each refresh token can be used only once. It should be secretly stored in your application.
You can get your refresh token from the authorization token’s response (/Token). By issuing a request with the refresh token, you get a new authorization token and a new refresh token.

POST /Token

Request Information

Header Parameters

Authorization: Basic [base64 encoding of {client_id:client_secret}]

URI Parameters

None.

Body Parameters

NameTypeDescription
grant_type String Type of grant required. Use “refresh_token”.
refresh_token String The refresh token from the authorization token request.

Request Format

application/x-www-form-urlencoded

POST https://api.cloud.materialise.com/Token HTTP/1.1
Content-Length: 92
Authorization: Basic YXBpdGVzdDo3ZjRlMDU4ZS00MGJlLTQ1NzktYTQxMC01YWM5ZDExYmRiOWI=
Content-Type: application/x-www-form-urlencoded
Host: api.cloud.materialise.com

grant_type=refresh_token&refresh_token=a5beac8430c64d81aa3282c9f19a183e

Response Information

Response Format

application/json

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 851
Content-Type: application/json;charset=UTF-8
Expires: -1
Date: Thu, 30 Jul 2015 09:08:39 GMT

{"access_token":"PSmVR2cKB_Ozjls-rDrGdNLetRyEdqeB4GwETTnukCWtSCsA6ve12-Gb_a6x1CvCATFKv5yBtQ7v_hvm3BdVOQNlBHoiTlPaDqLdTcK8Hdk38kv2iKJg3py_OCXwiZZRreMc9cSp1o-x6QIeoH4gahVct9weyRx99ToZYV-VTuOWYGQkmgpYj_pOefMRqTNqEbcjN-wghTR-uBtGLw5pPWOtI__3QP9FX_r9ofCx4bNNVYRTgHzfaap6tJ9XMwzlvyIZ34gceW792h7jzFkfRp74SCeUVsYACOJeVA3ZCt1nHXwAcWf-NvG7gdS0qhnD5eA40kB8Ix2xeGxGwAxZao0AdRIkoLlllo6iK3i40dJMktmCnrd1p5_f7AWmnwgn03zFtEJop0uwSv3LsG9qqURxvo-ccx-o9DxwelK1FLBIqy10dqV_8CkyCDOCwxi54Wn8x0VJ6vvCin7t5jOmyGQ_UiVRMrtYD-CLnp-8wV87Jqckve6fMGNhrIOsMbR3jltsMl3fqNBB4sDjyVI_GALxYx93Cm-0cs25uH8BrtJuoZJ5cU0QMH4zGD1OXRN9mj2tLg",
"token_type":"bearer",
"expires_in":899,
"refresh_token":"800933aef9d942839fe4176887830c5e",
"userName":"25bbc91c-a4ac-4877-b5a0-0aad9deb34c0",
"as:client_id":"apitest",
".issued":"Thu, 30 Jul 2015 09:08:38 GMT",
".expires":"Thu, 30 Jul 2015 09:23:38 GMT"}