Links

Retrieve and use project access tokens

Prerequisites

Create a project in the Dashboard and retrieve your client_id and client_secret in the API Credential Menu.

Retrieve access tokens

You can retrieve an access_token for your project with the Token API, using your client_secret, which you received with your client_id.
Example OAuth Token request
curl -v -X POST <https://oauth.swan.io/oauth2/token> \\
-d "client_id={YOUR_CLIENT_ID}" \\
-d "client_secret={YOUR_CLIENT_SECRET}" \\
-d "grant_type=client_credentials"
If you provided the correct client_id and client_secret, you should get a successful response with an access_token.
Example OAuth Token response
{
"access_token": "{YOUR_USER_ACCESS_TOKEN}",
"token_type": "bearer",
"expires_in": 3600,
"scope": ""
}
If you get an error here, such as 401 Unauthorized, this could have multiple reasons. It could for example be an invalid client_secret.

Act as a user with a project access token

User access tokens are necessary to know who is connected (userId) and who is performing sensitive operations, but they expire. If expiring user access tokens interrupt your automations, consider impersonating the user with a project access token instead.
To impersonate a user with a project access token:
  1. 1.
    Verify the user has signed into your project at least once.
  2. 2.
    Collect the Swan userId from the OAuth2 process to get a user access token.
  3. 3.
    Bind it with your own userId in your system.
  4. 4.
    Add the HTTP header x-swan-user-id with the userId (sample HTTP header line 2).
You can add this header to any GraphQL API request to impersonate the specified user; this method doesn't work with the OAuth2 API.
Sample of the HTTP header in a request
1
curl --location 'https://api.swan.io/live-partner/graphql' \
2
--header 'x-swan-user-id: 4d102f73-cc4a-4f2e-8734-e2885df95abd' \
3
--header 'Content-Type: application/json' \
4
--header 'Authorization: Bearer $PROJECT_ACCESS_TOKEN' \
5
--data '{"query":"query accounts {\n user {\n firstName\n lastName\n mobilePhoneNumber\n id\n }\n \n \n}\n","variables":{}}'
Then, you'll experience the environment as if you had used a user access token.
Approved use cases
  • Act as the legal representative to perform server consent operations​
  • Get updated or refreshed user data with a webhook notification on the user object
  • Illustrate a user's problem to Partners and Swan Customer Support
  • Use the Swan API on behalf of a user:
    • without a user access token
    • without asking the user to reconnect
    • without using the refresh token