/oauth/token

Last updated: March 7th, 2024.

Description.

This endpoint is used for getting a new token that will be used for consuming other zynchro.api microservices.

This endpoint must be consumed in POST request.

There are 2 types of use of this endpoint:

Getting access token
Refreshing access token

Getting Access Token

Request

As part of the request headers a Basic Auth must be sent.

Basic Auth Example

Basic Auth must be sent in the Http headers of the request. Look at the next curl example for a better understanding.

curl --location 'host:port/zynchro.api.security/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic **********************' \
--data-urlencode 'username=my_zynchro_username' \
--data-urlencode 'password=my_zynchro_pass' \
--data-urlencode 'grant_type=password'

In java it would look like this (depending on the dependency you use):

OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");

RequestBody body = RequestBody.create(mediaType, "username=my_zynchro_username&password=my_zynchro_pass&grant_type=password");

Request request = new Request.Builder()
  .url("host:port/zynchro.api.security/oauth/token")
  .method("POST", body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .addHeader("Authorization", "Basic **************************")
  .build();

Response response = client.newCall(request).execute();

These are the listed params required in the request body:

Request data
Field	SubField	Type	Desc	IsRequired
^username		^text	^{Username of the zynchro CMS system.} ^Example: ^{· zynchro_api} ^{Note: The user must have the API access grant in the CMS application}	^Y
^password		^text	^{The password of the provided user.} ^Example: ^{· ZyNcHr0S3cr3t}	Y
^grant_type			^{The grant type for getting a new access token for once or if it was invalidated by time expiration is:} ^{· password}	Y

Consuming Service

Example Request

Consuming service:

(POST) URL:http://IP:PORT/zynchro.api.security/oauth/token

Request Body params:

Request params in body

Example Response:

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDI1ODIzNjQsInVzZXJfbmFtZSI6ImFsZWphbmRyby56YW5hYnJpYUBkaWdpd29ya3MuY29tLm14IiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9TWVNURU1BRE1JTiJdLCJqdGkiOiJ5SjNxU1pLR1d0eFVoSWVPVl9JVGw1Z3Zza3ciLCJjbGllbnRfaWQiOiJ6eW5jaHJvIiwic2NvcGUiOlsicmVhZCIsIndyaXRlIl19.pUp9RuZgqyZp7gxqN1CfqVQjhzmOvC_VsTR928P1t8k",
    "token_type": "bearer",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJhbGVqYW5kcm8uemFuYWJyaWFAZGlnaXdvcmtzLmNvbS5teCIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJhdGkiOiJ5SjNxU1pLR1d0eFVoSWVPVl9JVGw1Z3Zza3ciLCJleHAiOjE3MDI2MTc3NjQsImF1dGhvcml0aWVzIjpbIlJPTEVfU1lTVEVNQURNSU4iXSwianRpIjoial8zS1RocjgycGo1YldBQVV4OWtidzJLVTZzIiwiY2xpZW50X2lkIjoienluY2hybyJ9.f3Bs4QBKiLVrJOD0b77J1DcwqhvX4wy4GJKH4A_gjAo",
    "expires_in": 598,
    "scope": "read write",
    "jti": "yJ3qSZKGWtxUhIeOV_ITl5gvskw"
}

Response:

Response 200 OK

Response
Field	SubField	Type	Desc
^access_token		^text	^{The access token that must be sended in the next request to other zynchro.api.* microservices}
^token_type		^text	^{The type of the token, always is type “bearer”}
^{refresh_token}		^text	^{The refresh token that must be sended when the access token expirates and the refresh token is still alive} ^{Please check the “Refreshing Access Token” section in this document for further information}
^expires_in		^int	^{The seconds left to expirate}
^scope		^text	^{The scope of the token, always must be “read write” because the api user access have read and write grants}
^jti		^text	^{The unique identifier to the requested token}

Response 400 Bad Request (Bad credentials)

If the user/pass you send is incorrect then the response will be http 400 Bad Request

{
    "error": "invalid_grant",
    "error_description": "Bad credentials"
}

Response 400 Bad Request (Unsupported grant type)

If the gran_type you send is different to “password” then you will receive the next message:

{
    "error": "unsupported_grant_type",
    "error_description": "Unsupported grant type"
}

Response
Field	SubField	Type	Desc
^error		^text	^{The identifier of the error.}
^{error_description}		^text	^{The description of the error.}

Response 401 Unauthorized

If you don’t send the Auth values in header (Authentication Basic) then you will receive the next message:

{
    "timestamp": "2023-12-14T20:33:54.712+00:00",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "/zynchro.api.security/oauth/token"
}

Response
Field	SubField	Type	Desc
^timestamp		^Text	^{The timestamp in UTC of the request.}
^status		^int	^{The http code of the response.}
^error		^text	^{The identifier of the error.}
^message		^text	^{The message of the error.}
^path		^text	^{The requested URL.}

Refreshing Access Token

Request

As part of the request headers a Basic Auth must be sent:

Basic auth example

This must be sent in the Http headers of the request, look at the next curl example for a better understanding.

curl --location 'host:port/zynchro.api.security/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic **************************' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJhbGVqYW5kcm8uemFuYWJyaWFAZGlnaXdvcmtzLmNvbS5teCIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJhdGkiOiJ6bTRCX0lycWlNN0JaVkxqeS1HV2VlSkc0ajAiLCJleHAiOjE3MDMxMzY4MDUsImF1dGhvcml0aWVzIjpbIlJPTEVfU1lTVEVNQURNSU4iXSwianRpIjoiRzF0ZUo4ak1yanBKTVZrWEN5Qk9pTmpJWDdRIiwiY2xpZW50X2lkIjoienluY2hybyJ9.YJN64rmiv5Hi2RkPoe8dvOE2jQ-ipBrH45TGz9Vvfb8'

Java would look something like this (depending on the dependency you use):

OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");

RequestBody body = RequestBody.create(mediaType, "grant_type=refresh_token&refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJhbGVqYW5kcm8uemFuYWJyaWFAZGlnaXdvcmtzLmNvbS5teCIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJhdGkiOiJ6bTRCX0lycWlNN0JaVkxqeS1HV2VlSkc0ajAiLCJleHAiOjE3MDMxMzY4MDUsImF1dGhvcml0aWVzIjpbIlJPTEVfU1lTVEVNQURNSU4iXSwianRpIjoiRzF0ZUo4ak1yanBKTVZrWEN5Qk9pTmpJWDdRIiwiY2xpZW50X2lkIjoienluY2hybyJ9.YJN64rmiv5Hi2RkPoe8dvOE2jQ-ipBrH45TGz9Vvfb8");

Request request = new Request.Builder()
  .url("host:port/zynchro.api.security/oauth/token")
  .method("POST", body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .addHeader("Authorization", "Basic **************************")
  .build();

Response response = client.newCall(request).execute();

These are the params required in the request body:

Request data
Field	SubField	Type	Desc	IsRequired
^grant_type			^{The grant type for refreshing a previously access token obtained is:} ^{· refresh_token}	^Y
^{refresh_token}			^{The refresh token.} ^Example: ^{eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJhbGVqYW5kcm8uemFuYWJyaWFAZGlnaXdvcmtzLmNvbS5teCIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJhdGkiOiJ6bTRCX0lycWlNN0JaVkxqeS1HV2VlSkc0ajAiLCJleHAiOjE3MDMxMzY4MDUsImF1dGhvcml0aWVzIjpbIlJPTEVfU1lTVEVNQURNSU4iXSwianRpIjoiRzF0ZUo4ak1yanBKTVZrWEN5Qk9pTmpJWDdRIiwiY2xpZW50X2lkIjoienluY2hybyJ9.YJN64rmiv5Hi2RkPoe8dvOE2jQ-ipBrH45TGz9Vvfb8} ^{Note: This refresh token is the value of the response when we call the token, see “Getting Access Token” section in this document for further information.}	^Y

Consuming Service

Example Request

Consuming service:

(POST) URL:http://IP:PORT/zynchro.api.security/oauth/token

Request Body params:

Body params example

Example Response

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDMxOTg1NTMsInVzZXJfbmFtZSI6ImFsZWphbmRyby56YW5hYnJpYUBkaWdpd29ya3MuY29tLm14IiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9TWVNURU1BRE1JTiJdLCJqdGkiOiJUbGJmT1UtTnMwNXBmUWlETjRfVHhVN2IyVVUiLCJjbGllbnRfaWQiOiJ6eW5jaHJvIiwic2NvcGUiOlsicmVhZCIsIndyaXRlIl19.2Bwz3ursoEquxk8j0GK1rCtCnS9fjGvgQlEjIIgOwh0",
    "token_type": "bearer",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJhbGVqYW5kcm8uemFuYWJyaWFAZGlnaXdvcmtzLmNvbS5teCIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJhdGkiOiJUbGJmT1UtTnMwNXBmUWlETjRfVHhVN2IyVVUiLCJleHAiOjE3MDMyMzM4NDMsImF1dGhvcml0aWVzIjpbIlJPTEVfU1lTVEVNQURNSU4iXSwianRpIjoidEg5X2JZa1ZrRGZXcEp0LXRUaTNwQWJJMjFzIiwiY2xpZW50X2lkIjoienluY2hybyJ9.SPJIFouCZJgcgC0DsJmqkCoP_Ubes75oTIs2eMGzVMs",
    "expires_in": 599,
    "scope": "read write",
    "jti": "TlbfOU-Ns05pfQiDN4_TxU7b2UU"
}

Response

Response 200 OK

Response
Field	SubField	Type	Desc
^access_token		^text	^{The access token that must be sended in the next request to other zynchro.api.* microservices}
^token_type		^text	^{The type of the token, always is type “bearer”}
^{refresh_token}		^text	^{The refresh token that must be sended when the access token expirates and the refresh token is still alive}
^expires_in		^int	^{The seconds left to expirate}
^scope		^text	^{The scope of the token, always must be “read write” because the api user access have read and write grants}
^jti		^text	^{The unique identifier to the requested token}

Response 400 Bad Request

If the grant_type is not passed, then you will receive the next message:

{
    "error": "invalid_request",
    "error_description": "Missing grant type"
}

If the refresh_token is not passed, then you will receive the next message:

{
    "error": "invalid_request",
    "error_description": "refresh_token parameter not provided"
}

If the gran_type we send is different to “password”, then you will receive the next message:

{
    "error": "unsupported_grant_type",
    "error_description": "Unsupported grant type"
}

If the refresh_token value you are sending is incorrect, then you will receive the next message:

{
    "error": "invalid_grant",
    "error_description": "Invalid refresh token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJhbGVqYW5kcm8uemFuYWJyaWFAZGlnaXdvcmtzLmNvbS5teCIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJhdGkiOiJldi1fWnZhWXd3N2xGRGFhZXoxNzJqVmpLQkEiLCJleHAiOjE3MDMyMzM4NDMsImF1dGhvcml0aWVzIjpbIlJPTEVfU1lTVEVNQURNSU4iXSwianRpIjoidEg5X2JZa1ZrRGZXcEp0LXRUaTNwQWJJMjFzIiwiY2xpZW50X2lkIjoienluY2hybyJ9.xN5Sa5qtyNWM_m1504AifX2EsGBCrvpG0jKlGi4MGSoeee"
}

Response 401 Unauthorized (Invalid Token)

If the refresh_token value is expired, then you will receive the next message:

{
    "error": "invalid_token",
    "error_description": "Invalid refresh token (expired): eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJhbGVqYW5kcm8uemFuYWJyaWFAZGlnaXdvcmtzLmNvbS5teCIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJhdGkiOiJ6bTRCX0lycWlNN0JaVkxqeS1HV2VlSkc0ajAiLCJleHAiOjE3MDMxMzY4MDUsImF1dGhvcml0aWVzIjpbIlJPTEVfU1lTVEVNQURNSU4iXSwianRpIjoiRzF0ZUo4ak1yanBKTVZrWEN5Qk9pTmpJWDdRIiwiY2xpZW50X2lkIjoienluY2hybyJ9.YJN64rmiv5Hi2RkPoe8dvOE2jQ-ipBrH45TGz9Vvfb8"
}

Response
Field	SubField	Type	Desc
^error		^text	^{The identifier of the error}
^{error_description}		^text	^{The description of the error}

Response 401 Unauthorized

If you don’t send the Auth values in header (Authentication Basic), then you will received the next message:

{
    "timestamp": "2023-12-14T20:33:54.712+00:00",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "/zynchro.api.security/oauth/token"
}

Response
Field	SubField	Type	Desc
^timestamp		^Text	^{The timestamp in UTC of the request.}
^status		^int	^{The http code of the response.}
^error		^text	^{The identifier of the error.}
^message		^text	^{The message of the error.}
^path		^text	^{The requested URL.}

Postman Collection:

Download file

zynchro.api.security_oauth_token.postman_collection.json

Knowledge Base

/oauth/token

Getting Access Token

Request

Consuming Service

Response:

Refreshing Access Token

Request

Consuming Service

Response