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&organization_id=OPTIONAL

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.
organization_id (optional extension to the OAuth2 protocol): The ID of the workspace that the user should be redirected to. If this is not provided and the user has multiple workspaces in their account, the user will be redirected to the workspace selection page.

2. The user signs 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.

Note that the parameters must be supplied in the body of a HTTP POST request and be url-encoded.

This is an example using the curl command line tool:

curl -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. This example uses the curl command line tool:

curl -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.

6. Switching workspaces¶

In all our APIs the workspaces feature is called organization. We therefore use the terms interchangeably. In order to switch workspaces, the OAuth2 flow must be restarted.

A list of the available organization IDs may be fetched from the /users/current endpoint (organization_memberships field). The organization_id may be given as a query parameter in the authorization URL (see step 1).