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.
Go to Studio settings -> Integrations -> Register Apps
Click “Add”
Choose Authorization Code for Allowed Grant Type.
Enter an application name and description if needed.
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:
Paste the generated URL into your browsers address bar.
Log in with the Creative Force user you want to authenticate with.
Click “Yes, Allow”
After the confirmation, your browser will be redirected to:
[Redirect URI]?code=[Authorization Code]&scope=[scope]&state=[state]
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: