Skip to content

OAuth2 flow

Follow these steps to implement the OAuth2 flow in your client application.

1) Start the authorization flow

You can start an authorization flow by redirecting the user to the following URL:

GET https://account.ultimaker.com/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SOME%20SCOPES&response_type=code&state=STATE
  • client_id: The client ID of your OAuth2 Client application.
  • redirect_uri: The URL to redirect back to after the user has logged in and approved access to their account.
  • scope: The OAuth2 scopes to apply to the resulting access token of the authorization flow. Multiple scopes can be requested using a space delimited notation. Be sure to URL encode the spaces using %20.
  • response_type: The OAuth2 response type, must be code.
  • state: A unique string that allows you to identify the specific authorization flow when it comes back to the redirect URL.

2) The user logs in

This step is executed on our servers. The user will log in using their Ultimaker account, give permission to your application and be redirected back to your redirect URL:

GET https://yourdomain.com/auth/redirect?code=AUTHORIZATION_CODE&state=YOUR_STATE
  • code: The temporary authorization code which is used in step 4 to request the access token.
  • state: The state that was sent in step 1. Can be used to identify the specific authorization flow.

3) Handle the redirect

On your redirect URL, you must implement functionality to get the code and state from the query parameters. These parameters are needed for requesting the access token in the next step.

4) Request the access token

The final step is to request the access token which can be used to access our services for the authorized user.

-X POST
-d "client_id=CLIENT_ID \
    &client_secret=CLIENT_SECRET \
    &redirect_uri=REDIRECT_URI \
    &grant_type=authorization_code \
    &scope=SOME SCOPES \
    &code=AUTHORIZATION_CODE"
https://account.ultimaker.com/token

Warning

The client secret is part of the request body. This means that this call should only happen from another server, never from a front-end application. If your application cannot use a server to make this request, consider using a proxy server that adds the secret to the request instead.

The response of this request will look like this:

{
    "token_type": "bearer",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o",
    "refresh_token": "486adfde-757b-4d37-81d7-446c2ec4bd91",
    "expires_in": 43199
}

Info

The access token is following the JWT standard, which allows for storing some user data in the token itself, so client side. For non-restrictive operations, like fetching basic user info, this token provides the API with all the data needed to validate the token without having to make a request to the authorization server. This saves time and resources. More elaborate API calls, like editing data, are still validated server-side by Ultimaker on each request.

5) Refreshing the access token

The access token token has a limited lifetime. This is denoted in the expires_in field in the token response. When using the token after the expiration time, a 401: Unauthorized will be returned by the API. When this happens, a refresh of the access token is needed. This can be done by using the refresh token that was also returned in the token response.

Do the following call to use the refresh token to request a new access token:

-X POST
-d "client_id=CLIENT_ID \
    &client_secret=CLIENT_SECRET \
    &redirect_uri=REDIRECT_URI \
    &grant_type=refresh_token \
    &scope=SOME SCOPES \
    &refresh_token=REFRESH_TOKEN"
https://account.ultimaker.com/token

The response to this request will look like this:

{
    "token_type": "bearer",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o",
    "refresh_token": "486adfde-757b-4d37-81d7-446c2ec4bd92",
    "expires_in": 600,
    "scope": "SOME SCOPES"
}

Both the access token and refresh token will be refreshed, so be sure to store this new refresh token as well in order to request a new access token the next time it expires.