Skip to content

Migration from v1 to v2

Example application

We have updated our example application to work with API v2. Download the updated example application.

Why did we migrate?

The migration to API v2 was driven by security improvements. We updated the authentication method to follow the Client Credentials flow of the OAuth 2.0 specification, replacing the legacy API key-only approach. This makes the integration more secure, better aligned with industry standards, and easier to audit.

What changed?

New Token Endpoint

The /authentication endpoint has been updated. Key changes:

  • The token endpoint is now hosted on a separate Identity server at https://identity.example.com. See the Authentication section of the API Reference for details.

  • You must URL-encode your client secret before using it. Use urlencoder.org to encode it.

  • The Authorization header must use the Basic scheme with a base64-encoded string of <ClientID>:<URL_Encoded_ClientSecret>.

    Encoding manually?

    Use base64encode.org to encode your credentials.

    5471E010-DDEE-4C98-FF8F-08DB2245E373:7rg6Gt+hUiobtXI9Jb37z2vtrhw1CEgDkwFZcMbN5Yc=

    NTQ3MUUwMTAtRERFRS00Qzk4LUZGOEYtMDhEQjIyNDVFMzczOjdyZzZHdCtoVWlvYnRYSTlKYjM3ejJ2dHJodzFDRWdEa3dGWmNNYk41WWM9

    Basic NTQ3MUUwMTAtRERFRS00Qzk4LUZGOEYtMDhEQjIyNDVFMzczOjdyZzZHdCtoVWlvYnRYSTlKYjM3ejJ2dHJodzFDRWdEa3dGWmNNYk41WWM9

  • The request body must include:

    • grant_type = client_credentials
    • scope = platform_upload_api
    • Content-Type: application/x-www-form-urlencoded

Example token request

curl --location 'https://identity.example.com/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic NTQ3MUUwMTAtRERFRS00Qzk4LUZGOEYtMDhEQjIyNDVFMzczOjdyZzZHdCtoVWlvYnRYSTlKYjM3ejJ2dHJodzFDRWdEa3dGWmNNYk41WWM9' \
-d 'grant_type=client_credentials&scope=platform_upload_api'

"eyJhbGciOiJSUzI1NiIsImtpZCI6IjBFNUMxNEU4OEIzRjFFMEFCNDlGNUIzMkU5NzNDMDQ0NkY0MjJDRURSUzI1NiIsInR5cCI6ImE0K2p3dCJ9..."

Upload API Endpoint

No major changes were made to the /UploadData request payload. However, the base URL for the Upload server has changed to https://web.example.com.

To authenticate requests, pass the token from the Identity server in the Authorization header using the Bearer scheme:

Bearer <token_string>

Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjBFNUMxNEU4OEIzRjFFMEFCNDlGNUIzMkU5NzNDMDQ0NkY0MjJDRURSUzI1NiIsInR5cCI6ImE0K2p3dCJ9...