Skip to main content

Overview

This guide covers the journey for a partner that owns the customer relationship in its own product and uses etoro as the brokerage and identity layer underneath. The user never has to register on etoro first. The journey has two parts, and they run on different channels:
Access is provisioned per partner. Before you start, your etoro contact must have set up your application (client credentials and redirect URIs), the scopes below, your API key, and the allow-listing of your egress IP addresses. See Before you start.
All endpoints in this guide are production endpoints. The authorization server is https://www.etoro.com; the API is https://public-api.etoro.com.

Before you start

Ask your etoro contact to confirm each of the following:
1

Application and credentials

A client_id and client_secret for your application, and the exact redirect URI or URIs you will use for silent login. Keep the secret on your backend only.
2

Scopes

The scopes this journey uses are listed below; the full scope map is in Permitted operations and scopes. A scope outside your grant is rejected.
3

API key and IP allow-listing

An x-api-key for your application, and your egress addresses registered with etoro, as described in the integration prerequisites.
4

Trusted-partner entitlement

Direct email and phone confirmation, and trusted user verification, are available only to partners etoro has approved as trusted, and only for users your application created.

Part A: Create the user and submit KYC

1. Obtain a partner token

Authenticate your application with the OAuth 2.0 client credentials grant. No end user is involved at this stage.
The response contains an access_token and the scopes granted to your application. Send the client secret in the form body, as above, or as HTTP Basic — not both. Request a new token when it expires. Which legal documents a user must accept depends on their country. Always fetch them for the country you are onboarding; never hard-code document identifiers.
Response 200
If blocked or restricted is true, do not continue to registration for that country. Present every returned document to the user, and record the time they accepted it and their IP address.

3. Register the user

Send one consents entry for every document returned in step 2.
No password is supplied; etoro generates one. A successful call returns 201 and a token bundle for the new user:
Response 201
Persist two values from this response:
  • The sub claim of the id_token. For a user this application registered, that claim is the externalUserId you send to silent login. It is not an etoro customer id. A person who already had an etoro account is the other path: you recognize them by the sign-in sub, and you read externalUserId from Associate the accounts.
  • The access_token. It is short-lived; honor expires_in. Use it as a bearer token for the next user-scoped calls, then replace it with a non-interactive token.
Common errors: 409 for a username, email, or partnerCorrelationId that is already in use (use new values); 422 for an invalid or missing consent, or a stale signedAt. See Errors and rate limits for the rest.

4. Issue a non-interactive token

The registration access_token expires. To keep calling user-scoped endpoints from your backend after that, issue a non-interactive token (NIT) for the user. The NIT published in this portal is the sub-account user token in Issue a non-interactive token. That call needs the registration access_token and an x-sub-account-id, and it returns the secret only once. Store it in a secret store, and set expiresAt and ipsWhitelist. Where the x-sub-account-id comes from depends on the path:
  • The person already had an etoro account and signed in. x-sub-account-id is the subAccountId from GET /api/v1/sub-accounts/me/accounts. See Associate the accounts.
  • Your application registered the user with POST /api/v1/registration/users. That response does not include a sub-account id. If you do not already have one, confirm the issuance path with your etoro contact before you build it. Do not call an internal host.
Until a NIT exists, user-scoped calls use Authorization: Bearer and the registration access_token. After it exists, they use your x-api-key and the user’s x-user-key. The two are mutually exclusive; see Issue a non-interactive token. The examples below show the key pair.

5. Prepare the profile and submit KYC

Call the operations below for the new user. Each lists the scopes it needs on its own page under Partners API. Where your own provider has already verified the user, you can supply that evidence instead of asking the user to repeat it.

Confirm email and phone with your own evidence

Direct confirmation records that you verified the email or phone, so etoro does not send a one-time code. Both calls take a verificationEvidence object:
phoneNumber is digits only, without the country code, and must be a valid national number for that country. A 409 means the email or phone is already verified, or is in use by another user; where the verification was intentional, treat an “already verified” response as done.

Submit trusted user verification

When the user has reached the required verification level, submit your verification evidence to complete trusted verification:
This operation requires the user to be at verification level 2 and then upgrades them to level 3. It is idempotent for a user already at level 3. If the user has not reached level 2, the call returns 400; complete the earlier profile and verification steps and check GET /api/v1/kyc/gaps rather than retrying. Use the verificationMethod value document_verification on this operation; the enumeration in the table above applies to the email and phone confirmations.
Trusted verification asserts that you verified the user. It is only accepted for users your application created, and you are accountable for the evidence you submit. Never send evidence for a verification that did not take place.

Part B: Sign the user in silently

Silent login opens etoro in the user’s browser already signed in. It is a handshake between the browser, your backend, and etoro, and the order matters.
Only etoro’s own page may set the login cookie. The cookie is created on etoro’s initiate page, in the user’s browser. Your application must never create, copy, forge, or proxy it. Do not call the initiate endpoint yourself. From your server, the cookie lands on the server and the browser never receives it. From your own page, the browser blocks the call. Either way, verify fails. That is expected behavior, not a defect.

1. Send the browser to etoro’s initiate page

When the user clicks “Open etoro”, send their browser to etoro’s initiate page, with a link or a redirect:
Use these names exactly, in snake case as in the OAuth login link. The page is the same for every partner, and the user does not need to be signed in to etoro first. The page sets etoro-silent-login-tid in the browser (HttpOnly, Secure, domain .etoro.com, about five minutes), then sends the browser to your callback:
Check that state is the value you sent for this attempt, and stop if it is missing or different. tid is a GUID with no dashes. If etoro rejects the request, for example because redirect_uri is not registered, the user sees an error page on etoro and does not come back to your callback.

2. Exchange the tid for a one-time token

On your backend, after the state check, read tid from the callback and identify the user. Authenticate with a partner token (see step 1 of Part A) and send the user’s externalUserId, which is the sub claim saved at registration:
Response 201
tid must be the GUID from the callback. externalUserId must be the value saved from registration and must belong to your application; a value minted for another application is rejected. This call needs the etoro-public:partner:silent-login:write scope on your partner token. It is granted per application, so a partner token that works for registration does not necessarily work here. It must be a partner token from the client credentials grant; a user access token is rejected with 401.

3. Open the verify URL in the same browser

Redirect the browser to the redirectUrl exactly as returned. Do not change its host, path, or query string. The etoro page combines the cookie from step 1 with the one-time token, establishes the session, and lands the user on etoro signed in. You do not call the verify endpoint yourself.

Timing and single use

  • The cookie lives for about five minutes. Complete steps 1 to 3 promptly.
  • The one-time token (ott) is single use. If a sign-in fails, start again from step 1; do not reuse an ott or a tid.
  • The cookie must come from the same browser that opens the verify URL.

From a native mobile app

The handshake is the same, but on mobile it is easy to lose the cookie between step 1 and step 3, because the two steps can end up in different browser contexts. Everything below follows from one rule: the browser context that opens the initiate page must still hold its cookies when it opens the verify URL. The simplest way to guarantee that is to keep the whole handshake inside the browser and never hand control back to the app in the middle:
  1. The app opens the initiate page in an external browser, as in step 1.
  2. etoro redirects that browser to your redirect_uri, which is an ordinary https endpoint on your backend, not a custom URL scheme.
  3. That endpoint checks state, calls partner-login-token server to server, and answers the browser with a 302 to the returned redirectUrl.
  4. The same browser follows the redirect to the verify URL and the user lands on etoro signed in.
The browser never leaves, so the cookie is still there, and your app does not have to move a tid or a URL across process boundaries. How to open that browser: An ephemeral session on iOS does work while it stays open, but it discards its cookies the moment it closes. If your flow closes the session at the callback and opens a second one for the verify URL, the cookie is gone and verify fails. Keeping the redirect inside a single browser session, as above, avoids the question. A redirect_uri using a custom scheme such as myapp://callback cannot be registered for silent login. Register an https callback on your backend.

Silent login errors

Errors and rate limits

Each operation’s rate limit is stated on its page under Partners API; most share a default of 60 requests per 60 seconds, and exceeding it returns 429. See Rate limits. Common causes of failure across the guide:

Go-live checklist

  • Consent documents fetched per country at registration time, never hard-coded, with an accurate signedAt and the end user’s own clientIp.
  • externalUserId (the sub claim) and partnerCorrelationId stored against your own user record.
  • Every item in the partner security checklist: NIT storage, expiry and IP restriction, egress allow-listing, and no personal data in logs or events.
  • Silent login started only by sending the user’s browser to etoro’s initiate page, with state checked on your callback and partner-login-token called only from your backend.
  • A full dry run of Part A and Part B in a non-production environment, agreed with your etoro contact, before any customer sees it.

Reference

Start here

Which path applies. Each operation page under Partners API lists the scopes it requires.

Partner integration flow

Non-interactive tokens, account association, scopes, and event reporting.

SSO with OAuth 2.0

The standard sign-in flow for users who already hold an etoro account.

API keys and headers

The x-api-key / x-user-key pair and request header format.