Authentication

Gojek uses standard OAuth2.0 authentication for integration with all of our partners. To complete the authentication process, the client must authorize itself to Gojek OAuth2 server.

Oauth2 credentials contain two parameters

• client_id

• client_secret

This identification of the client is done through client credentials issued by Gojek.

Pre-Requisite

Oauth2 credentials can be obtained via GoBiz Developer Portal. For detailed step by step please consult this section

How to get token?

We have 2 methods of getting token

Integration Type	Method to Get Token	When to Use?
Direct Integration Model	Client Credential grant_type=client_credentials	You’re a GoBiz merchant, and you want to access Gojek features directly from your own system.
Facilitator Model	Authorization Code grant_type=authorization_code	You’re a facilitator, either you a POS provider or an online order aggregator, and you want to link your Gojek merchants or access auth-code specific APIs.
Facilitator Model	Client Credential grant_type=client_credentials	You’re a facilitator and you have linked your merchants, and you want to enable Gojek features to your merchants.

Client Credential

You need to send a request to get access token. Token can be reused until it expired. Token lifespan is 3600 seconds by default. The required authentication parameters must be included in the request header at the time of the request.

Endpoint = {OAuth base URL}/oauth2/token

Request Body Parameters

Parameters	Type	Required	Description
client_id	string	Yes	Unique identifier issued to the client by Gojek.
client_secret	string	Yes	Secret issued to client by Gojek.
grant_type	string	Yes	Method to gain the access token. It must be client_credentials.
scope	string	Yes	Scope of access to be associated with the resulting access token.

Sample Request

Sample Request

curl -X "POST" "https://accounts.go-jek.com/oauth2/token" \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --user 'myclientid:myclientsecret' \
     --data-urlencode "grant_type=client_credentials" \
     --data-urlencode "scope=gofood:catalog:read gofood:catalog:write gofood:order:read"

Sample Response

Sample Response (200)

{
    "access_token": "{access_token_to_access_biz_env}",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "gofood:catalog:read gofood:catalog:write gofood:order:read"
}

Response Body Parameters

Parameters	Description
access_token	The token to access GoBiz endpoints.
scope	Space-separated authorized scopes.
expires_in	The approximate access_token's remaining lifetime in seconds since it was issued.
token_type	The type of the token. Always bearer.

See detailed flow and error response on API Reference

Authorization Code

Gojek is using terminology defined in RFC 6749: Section 1.1 - Roles and OpenID Connect Core 1.0 incorporating errata set 1.

Terms	Description
Resource Owner	GoBiz
Resource Server	GoBiz APIs
Client	Any web-app trying to access end-user’s information from GoBiz
Authorization Server	Gojek
Integrator	Organization integrating the client with GoBiz
User Agent	Interface used to redirect the user to Gojek and back. (i.e., browser)
Authorization Endpoint	{OAUTH_URL}/oauth2/auth
Token Endpoint	{OAUTH_URL}/oauth2/token
Access Token	Token required to access GoBiz APIs
ID Token	A JSON Web Token containing information about the user

Gojek requires integrator to provide redirection URIs (Refer RFC 6749: Section 3.1.2) which will be used for redirecting the user after authorization steps.

note

Refer OAuth 2.0: Section 2.3.1 - Client Password for more information on client credentials.

OAuth 2.0 and OpenID Connect are complex specifications with a lot of security considerations and implications. We recommend you use a pre-written, battle-tested client library suitable for the language/framework you are using for developing the client application. You can find a listing of such libraries at Code — OAuth (Not maintained by Gojek).

note

We strongly encourage you to refer OAuth 2.0 Threat Model and Security Considerations to ensure secure integration.

Create anti forgery state token

A state parameter is required for preventing request forgery attacks (Refer RFC 6749: Section 10.12). The state parameter is a unique session token that holds state between the client and the user agent (i.e., Browser). When the user is finally redirected back to the client after successful authentication & consent, client should cross verify this token to ensure the request is coming from legitimate user-agent and not a malicious attacker.

• state must be at-least 8 characters long
• state must be URL-safe encoded

Process authorization callback

Once the user successfully authenticates with Gojek and authorizes the client to access information, Gojek will generate an authorization code and redirect the user to redirect_uri with the code and the state that was originally sent by the client. On receiving this callback, client should verify the state parameter and ensure the value is same as the one sent by the client in previous step.

Exchange code for Access & ID tokens

The code returned in the previous step is one-time use only and is short-lived (Not more than 2 minutes after receiving the redirection). Client should exchange this code with Gojek to receive an access token and id token containing information about the user. A POST request should be sent to /oauth2/token endpoint with following parameters in the request body:

Endpoint = POST {OAuth base URL}/oauth2/token

Request Header

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

Request Body Parameters

Parameters	Type	Required	Description
client_id	string	Yes	Client identifier issued by GoJek and must be same as the one sent during /oauth2/auth.
client_secret	string	Yes	Client Secret issued by GoJek for the client_id.
grant_type	string	Yes	Method to gain the access token. It must be authorization_code.
code	string	Yes	Value received as part of redirection to redirect_uri.
redirect_uri	string	Yes	Redirection URI used during the /oauth2/auth call.

Sample Request

Sample Request

curl -X "POST" "https://accounts.go-jek.com/oauth2/token" \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "client_id=partner-client-id" \
     --data-urlencode "client_secret=partner-client-secret" \
     --data-urlencode "grant_type=authorization_code" \
     --data-urlencode "code=value-from-oauth-callback-queryparams" \
     --data-urlencode "redirect_uri=partner-redirect-uri"

Sample Response (200)

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "access_token": "{access_token_to_access_biz_env}",
    "expires_in": 3600,
    "id_token": "{id_token}",
    "scope": "offline email openid gofood:catalog:read gofood:catalog:write",
    "token_type": "bearer"
}

Response Body Parameters

Parameters	Description
access_token	The token to access Biz endpoints
scope	Space-separated authorized scopes
expires_in	The approximate access_token's remaining lifetime in seconds since it was issued
token_type	The type of the token. Always bearer
id_token	ID token
refresh_token	The refresh token, used to refresh the access token when expired.

Refreshing Access Token

When the access token expired, partner can request for new access token, given the refresh token available.

Endpoint = POST {OAuth base URL}/oauth2/token

Request Header

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

Request Body Parameters

Parameters	Type	Required	Description
client_id	string	Yes	Client identifier issued by GoJek and must be same as the one sent during /oauth2/auth.
client_secret	string	Yes	Client Secret issued by GoJek for the client_id.
grant_type	string	Yes	Method to gain the access token. It must be refresh_token.
refresh_token	string	Yes	Token to refresh the expired access token.

Sample Request

Sample Request

curl -X "POST" "https://accounts.go-jek.com/oauth2/token" \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "client_id=partner-client-id" \
     --data-urlencode "client_secret=partner-client-secret" \
     --data-urlencode "grant_type=refresh_token" \
     --data-urlencode "refresh_token=refresh-token"

Sample Response

Sample Response (200)

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8


{
    "access_token": "{access_token_to_access_biz_env}",
    "expires_in": 3600,
    "id_token": "{id_token}",
    "scope": "offline email openid gofood:catalog:read gofood:catalog:write",
    "token_type": "bearer"
}

Response Body Parameters

Parameters	Description
access_token	The token to access Biz endpoints
scope	Space-separated authorized scopes
expires_in	The approximate access_token's remaining lifetime in seconds since it was issued
token_type	The type of the token. Always bearer
id_token	ID token
refresh_token	The refresh token, used to refresh the access token when expired.