Develop
Develop
Select your platform

Account Linking

Updated: Oct 15, 2024
You can set up account linking between a user’s account in your system and their Meta account. This gives your system access to their alias, which is their Meta username, and their org-scoped ID, which is their identity across Meta Quest apps for your team.

Age-based feature limitations

When developing your apps, consider the following limitations related to age:
  • Child users under 13 (10-12 year olds): Regardless of your app’s self-certification status, child users under 13 cannot access this Platform SDK feature. Implement error-handling for this unsupported feature to maintain a safe and pleasant experience for child users.

Get started with account linking

This guide will cover how to set up account linking with in the developer dashboard, the user experience and the steps needed to retrieve an ID and alias. To use account linking you will need an app set up in the developer dashboard and user or test user accounts.

1. Register your login URL in the developer dashboard

To set up account linking for your app, you must first register an SSO URI in the developer dashboard.
  1. Log in to the developer dashboard. From the left naviagation panel, navigate to Team > SSO.
  2. Provide your login URI in the box provided and click Submit.

2. Create an account linking UI and forward user to Meta

From your app or website, you should provide the user with a button (or other UI) to opt in to their account in your system with their Meta account.
When the user clicks the button (or triggers the opt-in to their account through other UI), you should redirect them to Meta at the following URI, specifying your registered SSO URI and your Meta Quest team ID as query parameters:
https://auth.oculus.com/sso/?redirect_uri={yourLoginURL}&organization_id={yourMetaQuestOrganizationID}
If needed, the user logs in to Meta Quest, and then they confirm they want to link their account.
The following image shows an example of the account linking experience that the user will see:
When user clicks the Link Account button, you should redirect them by sending a GET request to the following URI:
https://auth.oculus.com/sso/?redirect_uri=https://someloginuri.com/oa&organization_id=1234567812345678

3. Extract the authorization code and user ID

When Meta Quest forwards users to your login URI, the URI contains base-64 encoded JSON appended to the URI. This JSON contains the authorization code and scoped user ID that you can use to retrieve an OAuth token. The URI is structured in the following way:
{yourLoginURL}#{base-64EncodedJSON}
For example:
https://someloginuri.com/oa#1234ImCiAib3JnLXNjb3BlZF9pZCI6ICIxMjM0NTY3ODEyMzQ1Njc4Igp9
When decoded results in the following:
{
 "code":"somecode",
 "org-scoped_id": "1234567812345678"
}
Make sure to save the user ID in your system so that you can use it to request refresh tokens.

4. Send the code and user ID and authorization info to request tokens

Use the info from the previous step along with the app ID and app secret to request an OAuth token. Your app ID and app secret can be found in the developer dashboard under Development > API. You must use an admin account to access the app secret from the API page.
Send a message like the following:
URI: https://graph.oculus.com/sso_authorize_code
METHOD: POST
Example message:
POST https://graph.oculus.com/sso_authorize_code?code=somecode
 &access_token=OC|client-id|client-secret&org_scoped_id=user-id-for-your-org
PARAMETERS:
ParameterParam TypeDescription
code
query
The access code obtained from the decoded result in step 3.
access_token
query
Token in the format OC|APPID|APPSECRET that contains the app ID and app secret found on the Meta Quest dashboard under Development > API > App Credentials.
org_scoped_id
query
The scoped identifier obtained from the decoded result in step 3.
Example success response:
The JSON response contains a 30-day OAuth token and refresh code.
{
    "oauth_token": "some-oauth-token",
    "refresh_code": "some-refresh-code"
}

5. Get the ID and alias for the user using the OAuth token.

Use the OAuth token received in the previous step to request the ID and alias for the user. Send a message like the following:
METHOD: GET
URI: https://graph.oculus.com/me
Example message:
GET https://graph.oculus.com/me?access_token=some-access-token&fields=id,alias
PARAMETERS:
ParameterParam TypeDescription
access_token
query
OAuth token retrieved in step 4.
fields
query
Comma separated list of user fields to retrieve. Only allowed values are id and alias.
Example success response:
The JSON response contains the user’s scoped ID and their Meta Quest alias.
{
    "id": "1234567812345678",
    "alias": "gamertag"
}
You should store the OAuth token for the user, and use it to make requests to Meta Quest on their behalf.

6. Use the refresh token when necessary

When the 30-day oauth token expires, retrieve a new one. Send a message like the following:
METHOD: POST
URI: https://graph.oculus.com/sso_authorize_refresh_code
Example message:
POST https://graph.oculus.com/sso_authorize_refresh_code?
 access_token=AppSecretToken&org_scoped_id=some-id&refresh_code=refresh-code
PARAMETERS:
ParameterParam TypeDescription
access_token
query
Token in the format OC|APPID|APPSECRET that contains the app ID and app secret found on the Meta Quest dashboard under Development > API > App Credentials.
org_scoped_id
query
The scoped identifier sent in the request to your login URL.
refresh_code
query
The refresh code from step 4.
Example success response:
The JSON response contains a 30-day OAuth token and another refresh code.
{
    "oauth_token": "some-oauth-token",
    "refresh_code": "some-refresh-code"
}
Did you find this page helpful?
Thumbs up icon
Thumbs down icon
Nav Logo
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
English (US)
© 2026 Meta