Identity Cloud and OAuth2

Mysoleas Identity Cloud is the user management service of the Mysoleas ecosystem. You can integrate it into your website, mobile application, or SaaS to manage authentication, user sessions, and profiles without rebuilding that whole layer yourself. In practice, your application can use Mysoleas Identity Cloud to:

display the Sign in with Mysoleas button;
authenticate a user with OAuth2/OIDC;
retrieve a user JWT and user claims;
read the user profile with userinfo;
delegate session and identity management to Mysoleas;
focus on your application’s own business logic.

You do not need to call the gateway to use Identity Cloud. Identity Cloud should not be presented as the main way to connect to the Mysoleas business ecosystem: it manages your users. If your application then consumes SoleasPay gateway endpoints, create an application in SoleasPay and use its client_id and client_secret to get the application token expected by x-sp-auth-token. The public authentication service is:

https://account.mysoleas.com

The public gateway is optional in an identity-only journey:

https://api.mysoleas.com

Create an OAuth2 application

Before you use OAuth2, create an application in the Mysoleas dashboard.

Create or use a Mysoleas account.
Sign in to the dashboard:

https://mysoleas.com

Open the OAuth2 applications section.
Create a new application.
Configure your allowed redirect URLs.
Copy the client_id and, if your application type allows it, the client_secret.
Enable the scopes required by your integration.

For a user-facing web or mobile application, prefer authorization_code with PKCE. Never place a client_secret in a frontend application.

Three different uses

Use	Domain	Credential obtained	Header used afterward
Authenticate your users only	`account.mysoleas.com`	User JWT and claims	Your application session
Call the SoleasPay gateway	Application created in SoleasPay then `api.mysoleas.com`	Token obtained from that application	`x-sp-auth-token: Bearer <SOLEASEPAY_APP_TOKEN>`
Server-to-server calls to your own backends	`account.mysoleas.com`	Application JWT	Backend-side validation
Checkout v4 or Button v4 plugin	`pay.soleaspay.com` or `btn.soleaspay.com`	No JWT	`apiKey` or `data-apikey`

If you call the Mysoleas gateway for SoleasPay endpoints, protected routes do not expect the Identity Cloud user JWT. Send the token obtained from the application created in SoleasPay in x-sp-auth-token.

Choose the right flow

Flow	When to use it
`authorization_code` with PKCE	Website, mobile application, or third-party application that displays Sign in with Mysoleas
`client_credentials`	Getting the token of an application created in SoleasPay for a backend, worker, or status synchronization
`refresh_token`	Renew a long-lived session without asking for credentials again

The recommended flow for a third-party application is authorization_code with PKCE. Your button must redirect the user to the Mysoleas authorization endpoint with your application’s OAuth2 parameters.

https://account.mysoleas.com/oauth/v2/authorize

Common parameters:

Parameter	Description
`client_id`	Your OAuth application identifier
`redirect_uri`	Return URL authorized in Mysoleas
`response_type`	`code`
`scope`	Requested permissions, for example `openid profile email payments`
`state`	Random value used to protect the callback
`code_challenge`	PKCE challenge
`code_challenge_method`	`S256`

Use Identity Cloud without the gateway

If your application only wants to delegate authentication to Mysoleas, the flow stops after JWT validation and the userinfo call. Your backend can then:

create or find the local user matching the sub claim;
attach the user to an organization, workspace, or tenant in your application;
open an application session;
apply your own roles and permissions;
continue using your own business APIs without going through api.mysoleas.com.

In this mode, Mysoleas Identity Cloud replaces the identity building block of your application. It does not force you to use the gateway.

Request a user token

After the OAuth2 callback, your backend exchanges the code for a user token.

curl -X POST "https://account.mysoleas.com/oauth/v2/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "code_verifier": "PKCE_CODE_VERIFIER",
    "redirect_uri": "https://yourdomain.com/oauth/callback"
  }'

The response follows the OAuth format.

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ..."
}

Call the SoleasPay gateway

If your application consumes SoleasPay endpoints through the gateway, use the credentials of the application created in SoleasPay.

curl -X POST "https://account.mysoleas.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "sp_client_id": "YOUR_SOLEASEPAY_APP_CLIENT_ID",
    "sp_client_secret": "YOUR_SOLEASEPAY_APP_CLIENT_SECRET"
  }'

All protected gateway routes then expect this token in x-sp-auth-token.

curl "https://api.mysoleas.com/service/list" \
  -H "x-sp-auth-token: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Use context headers

These headers are useful for multi-country integrations, separated environments, and debugging.

Header	Description
`x-sp-auth-token`	Required Bearer token obtained from an application created in SoleasPay
`X-Request-Id`	Trace id created by your system
`X-Idempotency-Key`	External idempotency key when the endpoint supports it
`X-SP-Country`	Active country, for example `CMR`
`X-SP-Environment`	`prod` or `dev`

OAuth discovery

You can read OAuth and OIDC metadata.

curl "https://account.mysoleas.com/.well-known/openid-configuration"

This route returns the official token, introspection, revocation, JWKS, and userinfo endpoints.

Best practices

Never put client_secret in the browser.
Renew the token before it expires.
Store tokens in memory or in a vault suited to your backend.
Use a stable idempotency key for every operation that can be replayed after a timeout.
Log transaction_reference, invoice_reference, and X-Request-Id together.

Get started

Payments

Catalog

Identity Cloud and OAuth2

Create an OAuth2 application

Three different uses

Choose the right flow

Use Identity Cloud without the gateway

Request a user token

Call the SoleasPay gateway

Use context headers

OAuth discovery

Best practices

​Create an OAuth2 application

​Three different uses

​Choose the right flow

​Integrate Sign in with Mysoleas

​Use Identity Cloud without the gateway

​Request a user token

​Call the SoleasPay gateway

​Use context headers

​OAuth discovery

​Best practices

Create an OAuth2 application

Three different uses

Choose the right flow

Integrate Sign in with Mysoleas

Use Identity Cloud without the gateway

Request a user token

Call the SoleasPay gateway

Use context headers

OAuth discovery

Best practices