Using Meta-API to authenticate end user with OAuth2

Video tutorial

Authentication profiles

OAuth's authentication accounts are capable of handling multiple profiles.

Once an authorization has been given, the account will appear in the list of profiles on the account configuration page

We can see that this OAuth configuration contains an active profile

If you have authorized several accounts, you will see the different accounts appear in the list (after refreshing the page):

It is possible to delete these profiles or to change the default account.

This default account will be used if no authentication profile is specified when calling the connector (details below).

⚠️ If a profile is deleted, it will be necessary to redo the authentication process for that profile.

Identifier management

Connector credentials are managed in three different ways:

• If the authentication API supports OpenID, this identifier will be retrieved and associated with the account. In case of manual renewal of the account, the profile will not be duplicated.
• If you have specified a custom ID (via the OAuth login button), it will be used. This method is very convenient if you want to use a custom ID like an email address or an ID from your own database.
• Otherwise, a UUID type identifier will be automatically assigned (ex: b5639e9a-c606-4f0d-8947-96a5360a1cd4). ⚠️ If this profile is reauthorized, it will be at risk of being duplicated.

Creating an OAuth login button

At the bottom of the OAuth configuration window, a drop-down panel provides instructions on how to create your own OAuth login button for your site:

The code displayed will be automatically customized according to your account.

You can use the example code or create your own button.

The classic way is to open in a new window the URL provided.

⚠️ If you are using an embedded view or popup on your site or an iframe, this can cause security issues with some APIs.

⚠️ Remember to customize or remove the userId parameter in the URL.

Using an authentication profile in a Spell

When you want to use a particular profile in a connector in your Spell, simply specify the account to use via the account configuration interface.

If no profile is specified when calling the connector, then the profile defined by default in the OAuth configuration will be used.

It is also possible to call a connector programmatically by using the variable system in the connector code.

To do this, declare a variable in the code that will carry the OAuth profile ID.

Then, click on the button to select your variable, the OAuth profile will be called dynamically.

Endpoint to manage profiles

Retrieve profiles

It is possible to retrieve the list of saved profiles via the following endpoint:

GET https://api.meta-api.io/api/clients/:CLIENT_ID/securities/:AUTH_ACCOUNT_ID/profiles

CLIENT_ID: Your client identifier. You can retrieve it by going on this page : My Subscription details and take your client ID inside the URL

AUTH_ACCOUNT_ID: identifier of the authentication account (present on the list of authentication accounts)

Authentication can be done either via API key (put apikey with the API key in the header, recommended method), or via the JWT key (put in the Authorization header). All active API keys will be valid.

This will give the list of profiles with some metadata:

[
  {
    "id": "https://login.salesforce.com/id/00D2X000003DmUAK/0052X0008NasQAC",
    "created_at": "2020-06-16T10:35:30.605Z",
    "updated_at": "2020-06-16T10:35:30.605Z",
    "scope": "openid api",
    "expiration": "2020-06-16T11:35:30.601Z",
    "hasRefreshToken": true,
    "isDefault": false
  },
  {
    "id": "https://login.salesforce.com/id/00D2X000003DmUAK/0052X0008NasQAC",
    "created_at": "2020-06-16T10:38:06.220Z",
    "updated_at": "2020-06-16T10:38:06.220Z",
    "scope": "openid api",
    "expiration": "2020-06-16T11:35:30.601Z",
    "hasRefreshToken": true,
    "isDefault": false
  },
  {
    "id": "test@test.com",
    "created_at": "2020-06-16T10:38:47.154Z",
    "updated_at": "2020-06-16T10:39:16.949Z",
    "scope": "openid api",
    "expiration": "2020-06-16T11:35:30.601Z",
    "hasRefreshToken": true,
    "isDefault": true
  }
]

It is also possible to add a query param id to filter only one profile.

Example of a query:

GET https://api.meta-api.io/api/clients/:CLIENT_ID/securities/:AUTH_ACCOUNT_ID/profiles?id="test@test.com"

Response:

[
  {
    "id": "test@test.com",
    "created_at": "2020-06-16T10:38:47.154Z",
    "updated_at": "2020-06-16T10:39:16.949Z",
    "scope": "openid api",
    "expiration": "2020-06-16T11:35:30.601Z",
    "hasRefreshToken": false,
    "isDefault": true
  }
]

Delete profiles

It is possible to delete profiles via the following endpoint:

DELETE https://api.meta-api.io/api/clients/:CLIENT_ID/securities/:AUTH_ACCOUNT_ID/profiles/:PROFILE_ID

Authentication is done, like the GET endpoint, via the apikey key in the header.

info

A connector is available on Meta API for this, you can find it here.