OAuth API
  • 08 Jul 2022
  • 3 Minutes to read
  • Dark
    Light

OAuth API

  • Dark
    Light

Document Version API Version Release notes Release Date Author
V1.0 V1 2022-05-19 Hardy, Cyrus

Contents

Authorize

The authorize endpoint can be used to request tokens or authorization codes via the browser. This process typically involves authentication and authorization confirmation of the end-user.

Get authorization code

GET /oauth/authorize

Parameters:

Name Type in Required Description
client_id string query yes Client ID.
response_type string query yes The value is "code".
redirect_uri string query yes Must exactly match one of the allowed redirect URIs for that client.

Response

  • Redirect to sign-in page
  • Redirect to grant-confirmation page
  • Redirect to redirect_uri with query parameters
Name Type in Description
code string query Authorization Code.

Example

Sample Request:

https://partner.comm100.io/oauth/authorize?client_id=1d29e6d7-18cf-407d-a064-e4f8c4baefab&response_type=code&redirect_uri=https://client1.company.com

Response

HTTP/1.1 302 Redirect
  • Redirect to https://partner.comm100.io/login?retUrl=https%3A%2F%2Fpartner.comm100.io%2Foauth%2FAccount%2FLogin%3FReturnUrl%3D%252Fconnect%252Fauthorize%252Fcallback%253Fclient_id%253Dclient1%2526response_type%253Dcode%2526redirect_uri%253Dhttps%25253A%25252F%25252Fclient1.company.com%25252Fauth%25252Foauth%25252Freturn%25252FComm100CLIAPI%25252F%2526scope%253Dids.scope%252520offline_access
  • Redirect to https://partner.comm100.io/oauth/account/login?ReturnUrl=%2Fconnect%2Fauthorize%2Fcallback%3Fclient_id%3Dclient1%26redirect_uri%3Dhttps%253A%252Fclient1.company.com%252Fauth%252Foauth%252Freturn%252FComm100CLIAPI%252F%26scope%3Dids.scope%2520offline_access
  • Redirect to https://partner.comm100.io/auth/oauth/return/Comm100CLIAPI/?code=******&scope=ids.scope%20offline_access
    image.png
  • Click the Allow button.
  • Redirect to https://client1.company.com/?code=4D5B8C97FBD59B5A01D9FB7C4FCCA8B7802652DFB274C3772BDF42E2C2DE9F76&scope=comm100%20offline_access%20openid&session_state=nJPx3fSHGXPpoYvr1YGCgntZ-mmNDwpK6DiIh82rEE0.8410B9C95EC984EA837765F7E6DFB171
    The code information is returned in above url 'code=4D5B8C97FBD59B5A01D9FB7C4FCCA8B7802652DFB274C3772BDF42E2C2DE9F76'.

Token

The token endpoint can be used to programmatically request tokens. It supports the password, authorization_code and refresh_token.

Token JSON Format

Token is represented as simple flat JSON objects with the following keys:

Name Type Description
access_token string Access token.
expires_in integer The lifetime in seconds of the token.
token_type string Token type.
refresh_token string The refresh token.

Request token by Authorization Code

POST /oauth/token

Parameters

Name Type In Required Description
client_id string form yes Client ID.
client_secret string form yes Client secret.
grant_type string form yes The value is "authorization_code".
redirect_uri string form yes Redirect URI.
code string form yes The authorization code.

Response

The response is a Token object.

Example

Sample Request:

curl https://partner.comm100.io/oauth/token  \
-H 'Content-Type:x-www-form-urlencoded'  \
-X 'POST'  \
-D 'client_id=1d29e6d7-18cf-407d-a064-e4f8c4baefab&client_secret=******&grant_type=authorization_code&code=4D5B8C97FBD59B5A01D9FB7C4FCCA8B7802652DFB274C3772BDF42E2C2DE9F76&redirec_uri=https://client1.company.com'

Response

HTTP/1.1 200 OK
Content-Type:  application/json
{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9.eyJuYmYiOjE2NTI5NDAwMDMsImV4cCI6MTY1Mjk4MzIwMywiaXNzIjoiaHR0cDovL2ludGVybmFsZGFzaC50ZXN0aW5nLmNvbW0xMDBkZXYuaW8iLCJhdWQiOiJpZHMucmVzb3VyY2UuMSIsImNsaWVudF9pZCI6InphcGllciIsInN1YiI6IjJmYTUwMGJmLTA2YWUtNGQ5YS1hNTA5LThjNjY5OGIxZTFjZiIsImF1dGhfdGltZSI6MTY1MjkzOTc2MiwiaWRwIjoibG9jYWwiLCJzaXRlSWQiOiI1MDAwMDAzIiwiYWdlbnRJZCI6IjJmYTUwMGJmLTA2YWUtNGQ5YS1hNTA5LThjNjY5OGIxZTFjZiIsInRodW1icHJpbnQiOiI5NjE2NkNBM0IzNEFCRjJEMDRERjk2QTAxNUJCREREMDlCMEE3QzU5Iiwic3VjY2VzcyI6IlRydWUiLCJyb2xlIjoiYWdlbnQiLCJqdGkiOiI5MzlGMTIxRkUwMEY1MTRCRkEzREYzNzU4MTEwNEQ0RiIsInNpZCI6IkVEMkEwMzNBMDNFOTFGOEFCNjhENUE2M0E3RkUwNTU4IiwiaWF0IjoxNjUyOTQwMDAzLCJzY29wZSI6WyJpZHMuc2NvcGUiLCJvZmZsaW5lX2FjY2VzcyJdLCJhbXIiOlsicHdkIl19.xbBhIjWmnNvbnJk2wPtV4kvdJeU8k3dUyq5vvLP5R1R-aA7VGaLTq5y7fROCv01ggsqoSH-YEsQvdh4xX9YZk5dP7O62OWxITwdH8Z27DN63cJ3TLwvMRbZaAqXzcd-mkR8f5NH57Un2E8jvTtmWq1N3rDB9D0dwECzWqbSd1FgHxDg3e_o5VsNgq2jCvyTBFDSDFvIerO2xIpZJ-zfI5dKa1lIdn-89l0IDS5Z4pCAbjEr2YPYqhFfguUvKvvpWoJX2ivRuFSlwuIkFes9ivWIFomZyHAjzLccNopT4nqBc_0UE-3xfnM0ukr0jUT2ig9DUrHE6G5AhskzxjNizNQ",
    "expires_in": 43200,
    "token_type": "Bearer",
    "refresh_token": "B9C62B757597F7C923415953512FB7DB2937BE065DDF920E8136DFECCFCBBB2B"    
}

Request token by Password

POST /oauth/token

Parameters

Name Type In Required Description
client_id string form yes Client id.
client_secret string form yes Client secret.
grant_type string form yes The value is "password".
email string form yes Resource owner email.
password string form yes Resource owner password.

Response

The response is a Token object.

Example

Sample Request:

curl https://partner.comm100.io/oauth/token  \
-H 'Content-Type:x-www-form-urlencoded'  \
-X 'POST'  \
-D 'client_id=1d29e6d7-18cf-407d-a064-e4f8c4baefab&grant_type=password&email=client1@company.com&password=******'

Response

HTTP/1.1 200 OK
Content-Type:  application/json
{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9.eyJuYmYiOjE2NTI5MzkzOTEsImV4cCI6MTY1Mjk4MjU5MSwiaXNzIjoiaHR0cDovL2ludGVybmFscGFydG5lci50ZXN0aW5nLmNvbW0xMDBkZXYuaW8iLCJhdWQiOiJpZHMucmVzb3VyY2UuMSIsImNsaWVudF9pZCI6ImRhdGFzeW5jIDEwMDAwIiwic3ViIjoiYmZlYjQ1ZDctNTBkYy00MTZkLWIzYzgtMzVkYjY0ZDI4OGYzIiwiYXV0aF90aW1lIjoxNjUyOTM5MzkxLCJpZHAiOiJsb2NhbCIsInVzZXJJZCI6ImJmZWI0NWQ3LTUwZGMtNDE2ZC1iM2M4LTM1ZGI2NGQyODhmMyIsInBhcnRuZXJJZCI6IjEwMDAwIiwidGh1bWJwcmludCI6Ijk2MTY2Q0EzQjM0QUJGMkQwNERGOTZBMDE1QkJEREQwOUIwQTdDNTkiLCJzdWNjZXNzIjoiVHJ1ZSIsInJvbGUiOiJVc2VyIiwianRpIjoiODVFNzUzQTYwRDY4MzI4MjlEMkU4MDEwNUU3NTAwNjIiLCJpYXQiOjE2NTI5MzkzOTEsInNjb3BlIjpbImlkcy5zY29wZSIsIm9wZW5pZCIsInByb2ZpbGUiLCJvZmZsaW5lX2FjY2VzcyJdLCJhbXIiOlsicHdkIl19.ADZQq2R3-zJl_Bg9jOUREvrXvvmLc669iZSUZhU6oRmd6vu1UXU8VkXgxQZSk4pFxCW7j2UGuDi0jTF27e5W4PzyGWmE-qj9gE-iY9b7PSOPwYENS8rylFwB3dL7f_qlQCbzQ2kUoCoAlIPLqVbQHN76ftMoo57Ge9rg0xOw-BJT4GBKiflgE6dz8ikQhlg7_DAM-JY51Vk7bmsvny356P5Rv5cdJnBvrCCqAJeV-Y5jzUblAKx61HSZE9gBoRhYOprYgK37pw3XMqG9H5BvCr32DSufA0U91rA1sOX945yNLrYAAsDHlMO2-nmEHgOMFrnIOvzsgjnMktcxkR0NQG",
    "expires_in": 43200,
    "token_type": "Bearer",
    "refresh_token": "F13741023427FFB7404FDE64EF485D858721D88A488763592B08CF303E721BE0",
    "scope": "comm100 offline_access"
}

Refresh_token

POST /oauth/token

Parameters

Name Type In Required Description
client_id string form yes Client ID.
client_secret string form yes Client secret.
grant_type string form yes The value is "refresh_token".
refresh_token string form yes The refresh token.

Response

The response is a Token object.

Example

Sample Request:

curl https://partner.comm100.io/oauth/token  \
-H 'Content-Type:x-www-form-urlencoded'  \
-X 'POST'  \
-D 'client_id=1d29e6d7-18cf-407d-a064-e4f8c4baefab&client_secret=******&grant_type=refresh_token&refresh_token=F13741023427FFB7404FDE64EF485D858721D88A488763592B08CF303E721BE0'

Response

HTTP/1.1 200 OK
{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9.eyJuYmYiOjE2NTI5NDAxODIsImV4cCI6MTY1Mjk4MzM4MiwiaXNzIjoiaHR0cDovL2ludGVybmFscGFydG5lci50ZXN0aW5nLmNvbW0xMDBkZXYuaW8iLCJhdWQiOiJpZHMucmVzb3VyY2UuMSIsImNsaWVudF9pZCI6ImRhdGFzeW5jIDEwMDAwIiwic3ViIjoiYmZlYjQ1ZDctNTBkYy00MTZkLWIzYzgtMzVkYjY0ZDI4OGYzIiwiYXV0aF90aW1lIjoxNjUyOTQwMTc0LCJpZHAiOiJsb2NhbCIsInVzZXJJZCI6ImJmZWI0NWQ3LTUwZGMtNDE2ZC1iM2M4LTM1ZGI2NGQyODhmMyIsInBhcnRuZXJJZCI6IjEwMDAwIiwidGh1bWJwcmludCI6Ijk2MTY2Q0EzQjM0QUJGMkQwNERGOTZBMDE1QkJEREQwOUIwQTdDNTkiLCJzdWNjZXNzIjoiVHJ1ZSIsInJvbGUiOiJVc2VyIiwianRpIjoiQ0Q4QTZCNjU4QzNGODZFMzBEN0REQkZBODM2RkVEM0IiLCJpYXQiOjE2NTI5NDAxNzQsInNjb3BlIjpbImlkcy5zY29wZSIsIm9wZW5pZCIsInByb2ZpbGUiLCJvZmZsaW5lX2FjY2VzcyJdLCJhbXIiOlsicHdkIl19.zSMnpHkpVBkuIhoiTMWQxWDszPZASTffnMO8cD8xmsmkVRdGJZlRmfcvg6HWi4OR1Ik9dfFHTL-T7UNM-8c4eoHc3lbooWyITk6RJ_JvYQI1bQ-eaaAXeRuvbn9VH3IfM9cy2KYChlPd2A6Ul7W7mVXP61SSjKjioOzZmtdFAkHtZmtJo5a1b0ed6Rk9e1_7wjS2i6YVf1lcJaLD3B4KmIYJHlwAVZs6m2xDqZASaFhim9rdF1iw4Lvn0EM2p6LkE41oWRUSClrtHIEvTjNNXqyjwNd1885JTLhu8qyNM9yZDVg9j0MISYgt0p-eUVCNx6vpXy_XmkjJnv4TS2mHWW",
    "expires_in": 43200,
    "token_type": "Bearer",
    "refresh_token": "ECC1CCF28E73B9F241D3433CC0A7D91E5CC2760F43230510A74F4F01A39BAD7F",
    "scope": "comm100 offline_access"    
}

User Info

The UserInfo endpoint can be used to retrieve identity information of a user.

User Info JSON Format

User Info is represented as simple flat JSON objects with the following keys:

Name Type Read-only Mandatory Description
sub string yes no Subject.
auth_time long yes no Timestamp in seconds.
idp string yes no IDP.
agentId string yes no Agent ID.
siteId string yes no Site ID.
userId string yes no User ID.
partnerId string yes no Partner ID.
thumbprint string yes no Thumbprint.
success bool yes no Whether success or not.
role string yes no Role.
arm string yes no ARM.

Get user info

GET /oauth/userinfo

Parameters

Name Type In Required Description
Authorization string header yes Bearer <access_token>.

Response

The response is a User Info object.

Example

Sample Request:

curl https://partner.comm100.io/oauth/userinfo  \
-H 'Authorization:Bearer <access_token>'  \

Response

HTTP/1.1 200 OK
Content-Type:  application/json
{
    "sub": "bfeb45d7-50dc-416d-b3c8-35db64d288f3",
    "auth_time": 1652940304,
    "idp": "local",
    "userId": "ffeb45d7-50dc-416d-b3c8-35db64d288f3",
    "partnerId": "10000",
    "thumbprint": "96166CA3B34ABF2D04DF96A015BBDDD09B0A7C60",
    "success": "True",
    "role": "User",
    "amr": "pwd"
}

Was this article helpful?

What's Next