OAuth2 Authentication on the Yapla Platform

Discover the process to obtain an access token via the OAuth2 protocol. This token is required to make secure calls to the Yapla GraphQL API on behalf of a user.

Supported Authentication Flows

Yapla supports two standard and secure flows:

Authorization Code Flow: Ideal for traditional web applications where the Client Secret can be securely stored on a server.
Authorization Code Flow with PKCE (Proof Key for Code Exchange): Recommended for public clients, such as mobile applications or single-page web applications (SPAs), where the Client Secret cannot be securely stored.

Step 1: Obtain Your OAuth Client Credentials

Before you can connect to the API, you need to get a Client ID and, if necessary, a Client Secret. These credentials are unique to your application.

Required Action:

To receive your credentials, please send an email to support@yapla.com with the following information:

Application Name: A descriptive name for your project.
Client Type: Specify if your application is confidential (web server) or public (SPA, mobile).
Description of Your Needs: Briefly explain what your integration will be used for and the permissions (scopes) you think you'll need. The scopes applicable to your client will be communicated by our team based on this description.
Redirect URIs: The full URL(s) to which Yapla will redirect the user after they authorize your application. These URLs must be precise and secure (https).

Our team will process your request and securely return your Client ID (and Client Secret if applicable).

Step 2: Redirect the User to the Consent Page

The first step is to redirect the user to Yapla's consent page.

A. Generate `code_verifier` and `code_challenge` (For PKCE only)

If you are using the PKCE flow, you must first generate:

A code_verifier: A high-entropy random string.
A code_challenge: The Base64 URL-encoded SHA-256 hash of the code_verifier. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

You must store the code_verifier to use it in Step 3.

B. Build the Authorization URL

You need to construct a URL in the following format:

https://login.yapla.com/oauth/authorize?response_type=code&client_id=[YOUR_CLIENT_ID]&redirect_uri=[YOUR_REDIRECT_URI]&scope=[ASSIGNED_SCOPES]&state=[RANDOM_VALUE]&code_challenge=[PKCE_CHALLENGE]&code_challenge_method=S256

URL Parameters:

response_type=code: Fixed value.
client_id=[YOUR_CLIENT_ID]: Your client ID.
redirect_uri=[YOUR_REDIRECT_URI]: Must exactly match one of the provided URIs.
scope=[ASSIGNED_SCOPES]: The list of permissions (separated by spaces) assigned to you.
state=[RANDOM_VALUE]: A random string to prevent CSRF attacks. Verify it upon return.
code_challenge=[PKCE_CHALLENGE]: (PKCE) The generated challenge.
code_challenge_method=S256: (PKCE) Indicates the challenge was hashed with SHA-256.

After giving consent, the user is redirected to your redirect_uri with a code and the state in the URL parameters.

Step 3: Exchange the Authorization Code for an Access Token

With the received code, your application must make a POST request to Yapla's token endpoint to get the access_token.

Endpoint: POST https://login.yapla.com/oauth/token Header: Content-Type: application/x-www-form-urlencoded

Request Body:

grant_type: authorization_code
code: The authorization code received.
redirect_uri: The same redirect URI.
client_id: Your Client ID.
client_secret: (Non-PKCE) Your Client Secret.
code_verifier: (PKCE) The original code_verifier you generated and stored.

Example with curl (PKCE Flow):

curl -X POST \
  https://login.yapla.com/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'code=[RECEIVED_CODE]' \
  -d 'redirect_uri=[YOUR_REDIRECT_URI]' \
  -d 'client_id=[YOUR_CLIENT_ID]' \
  -d 'code_verifier=[YOUR_CODE_VERIFIER]'

Expected Response (JSON):

{
  "access_token": "xyz789...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "abc123...",
  "scope": "c3_12345 c3_67890"
}

Store the access_token and refresh_token securely.

Step 4: Use the Access Token

You can now use the access_token to make authenticated calls to the Yapla GraphQL API.

API Endpoints:

North America: https://s1.yapla.com/graphql
Europe: https://s2.yapla.com/graphql

Example API Call:

curl -X POST \
  https://[s1|s2].yapla.com/graphql \
  -H 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
  -H 'Content-Type: application/json' \
  -d '{"query": "{ company { name } }"}'

Congratulations, your application is now connected to the Yapla API!