Skip to main content

Authentication

To securely access the API, our system uses the OAuth 2.0 protocol, ensuring that all integrations are safe and that user data remains protected. Before a developer can use our OAuth 2.0 flow to integrate their app, they must first request a partnership.

Partnership Request Process​

In order to access and use our API via OAuth 2.0, you will need to first request a partnership. This step is required to verify the legitimacy of your app and to establish a trusted connection between our services and your integration.

Contact our support team to begin the partnership process.

OAuth 2.0 Authentication​

Once your partnership request is approved, you can integrate our API using OAuth 2.0. This section will guide you through the OAuth 2.0 flow and explain how to securely authenticate your app and obtain access tokens. Learn more about OAuth 2.0 here.

There are several OAuth 2.0 grant types, but Harlyy uses the Authorization Code Grant. Here’s how it works:

  • Step 1: User authorization request (user signs in and consents).
  • Step 2: Your app receives an authorization code.
  • Step 3: Your app exchanges the authorization code for an access token.
  • Step 4: Use the access token to make API requests.

Create Credentials​

You can create a set of credentials, including a clientId, clientSecret and a set of validRedirectUris, by going to the credentials page in the Business Portal. See the Credentials Reference to see how to programatically create and manage credentials.

OAuth Endpoints​

The Harlyy OAuth service uses standard OAuth endpoints, these endpoints use the https://auth.harlyy.com endpoint. View the Tokens Reference from additional details on how they can be used when creating, issuing and managing tokens.

Authorization Endpoint
GET /oauth/authorize
Token Endpoint
POST /oauth/token
Revocation Endpoint
POST /oauth/revoke
Who am I Endpoint
POST /oauth/me
Public Certificates Endpoint
GET /oauth/certs

Example Flow​

Redirect to Authorization Endpoint​

Direct your users to our authorization URL, along with your app’s clientId and redirectUri.

Authorization Endpoint
https://auth.harlyy.com/oauth/authorize?
  responseType=code&
  clientId=YOUR_CLIENT_ID&
  redirectUri=YOUR_REDIRECT_URI&
  scope=YOUR_SCOPES&
  state=YOUR_STATE
  • responseType: Set this to code.
  • clientId: A clientId which you can setup via the Business Portal.
  • redirectUri: An authorized origin, this is also to be setup via the Business Portal.
  • scope: A comma separated list of permissions your app is requesting. See the Tokens Reference for available scopes.
  • state: A random string to prevent CSRF attacks (optional, but recommended).

User Grants Permission​

The user will login in and grant your app the requested permissions. After consent, they will be redirected back to the redirectUri you specified, along with an authorization code.

Callback
GET https://youapp.com/callback?code=AUTH_CODE&state=YOU_STATE
  • code: The authorization code.
  • state: A value to verify that this request is in response to your original authorization request, this should match the value you provided in the authorization request (if you provided one).

Exchange Authorization Code for Access Token​

After receiving the authorization code, exchange it for an access token by making a POST request to our token endpoint.

Token Endpoint
POST https://auth.harlyy.com/oauth/token
Content-Type: application/json

{
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "grantType": "authorization_code",
  "code": "AUTH_CODE"
}
  • clientId: Your client ID you received.
  • clientSecret: Your client secret.
  • grantType: Set this to authorization_code.
  • code: The authorization code from Step 2.

Receive Access Token​

If successful, you’ll receive an access token and optionally a refresh token in the response.

Returns Tokens
{
  "id": "tk_674654e941e47f12ff986104",
  "accessToken": "ACCESS_TOKEN",
  "refreshToken": null,
  "scope": ["https://www.harlyy.com"],
  "credential": "cred_673bc340ff96e945d8fdf514",
  "user": "user_673d08c9048fcc5d37aeb5cb",
  "issuedAt": 1732662505574,
  "expiresAt": 1732669705574
}

Refresh an Expired Token​

When the access token expires, you can use the /oauth/token endpoint if you have a refresh token, in order to get a new access token.

Getting the User Information​

Once you have any token, can get the user information by making a request to the /oauth/me endpoint with the access token in the Authorization header.

Validating Harlyy Tokens​

It is highly recommended for you to validate all tokens you receive from Harlyy. You can do this by making a request to the /oauth/me endpoint with the access token in the Authorization header, or preferably by using the public certificates to validate the token signature yourself. Harlyy uses the RS512 algorithm to sign the tokens.

The Certificate Object​

Schema Certificate not found in OpenAPI spec.