All Collections
IT/Security
Integrations
Getting started with Authorization Code Grant Flow for Creative Force Gateway API
Getting started with Authorization Code Grant Flow for Creative Force Gateway API

This article describes how to get started integrating with the Creative Force Gateway API.

Tejs Rasmussen avatar
Written by Tejs Rasmussen
Updated over a week ago

The Creative Force Gateway API uses OAuth 2.0. OAuth 2.0 is a protocol that lets your app request authorization to private details in a user's Creative Force account without getting their password. Your app asks for specific permission scopes and is rewarded with access tokens upon a user's approval.

Available Creative Force Gateway API methods can be found here:
developers.creativeforce.io


The OAuth Flow

Creative Force Gateway API uses OAuth 2.0's authorization code grant flow to issue access tokens on behalf of users.

The OAuth flow is your key to unlocking access tokens. There's no path to programmatically create (or retrieve) app access tokens without a user's input.


Step 1. Register App

You'll need to register your app before getting started. A registered app is assigned a unique Application ID (OAuth: Client ID) and Secret Key (OAuth: Client Secret) which will be used in the OAuth flow. The Client Secret should not be shared.

  1. Go to Studio settings -> Integrations -> Register Apps

  2. Click “Add”

  3. Choose Authorization Code for Allowed Grant Type.

  4. Enter an application name and description if needed.

  5. Add a Redirect URI

Regarding Redirect URI

In order to generate an authorization code, you need to add a redirect URI. This is where your user will be sent after he has authorized your application to access Creative Force on his behalf.

Please notice that the following URIs are NOT allowed:

  • "localhost"

  • "creativeforce.io"

  • "metadata.google"

  • "burpcollaborator.net"

  • ".local"

  • ".internal"

  • "ram.aliyuncs.com"

  • "fuf.me"

  • "localtest.me"

  • "ulh.us"

  • "127.0.0.1"

  • "169.254.169.254"

⚠️ The Redirect URI will be validated with an nslookup and therefore has to be accessible from the Creative Force system.

Regarding Post Logout Redirect URI

If you want to control where users are sent in case they log out of Creative Force before authentication has been completed, you can add a Post Logout Redirect URI. This is not mandatory.


Step 2. Authorization Code

Depending on the kind of integration you are making, you either need to generate an authorization code that you manually copy and use in your application or have an application on the redirect URI that can receive and store the Authorization Code. In this example, we will be talking about the manual solution.

The user

You will need a Creative Force user with Developer API permissions.
Please see this article on how to set up user roles and permissions.

Obtaining the Authorization Code

To obtain an Authorization Code, you will need to combine the information below into a URL.

Authorization Code URL

https://accounts.creativeforce.io/connect/authorize

Parameters

  • client_id=[Application ID from the registered App]

  • redirect_uri=[URL encoded redirect URI. Must match with App settings]

  • scope=cfgateway offline_access openid

  • response_type=code

  • state=[Can be anything needed to validate the callback.]

A note on scope: cfgateway is Required to access the Creative Force Gateway API. offline_access is needed to enable token refresh and to allow integrating applications to access the API, when the user is not logged in. openid is needed to get the id_token that is used to authorization code flow logout. Both offline_access and openid are optional.

URL Example

https://accounts.creativeforce.io/connect/authorize?client_id=717ed07d-j3k6-4f01-l3h8-dfbe5a0d2a31&scope=cfgateway%20offline_access&redirect_uri=https%3A%2F%2Fwww.creativeforce.io%2Fproduct&response_type=code&state=abc

To manually get the authorization code, perform the following steps:

  1. Paste the generated URL into your browsers address bar.

  2. Log in with the Creative Force user you want to authenticate with.

  3. Click “Yes, Allow”

    After the confirmation, your browser will be redirected to:
    [Redirect URI]?code=[Authorization Code]&scope=[scope]&state=[state]

  4. From the address bar, copy the Authorization Code.

⚠️ Please note that the Authorization Code will expire after 30 minutes.


Step 3. Get user access token

To get the user access token, you should programmatically (or via Postman, curl or similar tools) make a request to the URL stated below using the parameters listed.

User access token URL

https://accounts.creativeforce.io/connect/token

Parameters

  • client_id=[Application ID from the registered App]

  • client_secret=[Secret Key from the registered App]

  • scope=cfgateway offline_access openid

  • grant_type=authorization_code

  • code=[Your generated Authorization Code]

  • redirect_uri=[Redirect URI. Must match with the registered app settings]

Example

curl --location --request POST 'https://accounts.creativeforce.io/connect/token' \
--header 'User-Agent: TestClient/1.0' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=717ed07d-ssdkdk-j3j4j4h2-2i3i4y' \
--data-urlencode 'client_secret=4c9sajk34jjdak33jeakelad24' \
--data-urlencode 'scope=cfgateway offline_access openid' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=8659m1X-k-1q1LRp24pwjK47UyQZOFii9i4JClyqQno' \
--data-urlencode 'redirect_uri=https://www.creativeforce.io/product'


The result of the request will be an access_token, a refresh_token, and an id_token. The refresh_token only returns if the scope contains offline_access. The id_token only returns if the scope contains openid.

These tokens should be stored and used for API requests on the Creative Force Gateway API.

Refreshing an expired user access token

User access tokens will expire after 1 hour and will have to be refreshed.

Refresh tokens will expire after 30 days. When an expired token is used for an API request the API response code will be 401. Token refresh requests are performed as outlined below.

Refresh token URL

https://accounts.creativeforce.io/connect/token

Parameters

  • client_id=[Application ID from the registered App]

  • client_secret=[Secret Key from the registered App]

  • scope=[Use the same scope as when you generated the Authorization Code]

  • grant_type=refresh_token

  • refresh_token=[The refresh_token from step 3]

Example

curl --location --request POST 'https://accounts.creativeforce.io/connect/token' \
--header 'User-Agent: TestClient/1.0' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=717ed07d-ssdkdk-j3j4j4h2-2i3i4y' \
--data-urlencode 'client_secret=4c9sajk34jjdak33jeakelad24' \
--data-urlencode 'scope=cfgateway offline_access' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=K9B1oTVCf2WeGTasdasdasdwwdcc'


Making API Requests

When making requests to the Creative Force Gateway API, you must use the user access token as part of your request.

Example

curl --location --request GET 'https://gateway.creativeforce.io/v1/products/get-status?productCode=gcs1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer jG0iaVeyyatICNylTVD_Ux0K64FXJkgM0dzbQ'

Step 4. Logout

This is an optional step. You do not need to logout if you don’t want to.

Revoke Access Token or Refresh Token

This endpoint allows revoking access token and refresh token.

Revocation URL

Headers:

  • Content-Type: application/x-www-form-urlencoded

  • Authorization: Basic base64-encoded(client_id:client_secret)

Parameters:

  • token: the token to revoke

  • token_type_hint: either "access_token" or "refresh_token"

Example

curl --location --request POST 'https://accounts.creativeforce.io/connect/revocation' \

--header 'Authorization: Basic NzE3ZWQwN2Qtc3Nka2RrLWozajRqNGgyLTJpM2k0eTo0YzlzYWprMzRqamRhazMzamVha2VsYWQyNA==' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--data-urlencode 'token=4Uxt29TR8bsQAxl8_KiiTURYlOmmE_THBw' \

--data-urlencode 'token_type_hint=access_token'

End Session

End the session on http://accounts.creativeforce.io but not revoke the issued tokens.

After end session your browser will be redirected to the [Redirect URI]

End session URL

Parameters:

  • id_token_hint: the 'id_token' which was returned from “Step 3. Get user access token”

  • post_logout_redirect_uri: one of POST LOGOUT REDIRECT URI in the application setting, the value must be encoded.

Example URL:

Did this answer your question?