RESTful API
PluginLab has a RESTful API that makes it possible for developers to interact with their member's data.
Thanks to this API you can manage your members and do some daily operations such as fetching users, updating them and more.
Note: this guide is describing how to use our RESTful API. If you are looking to implement it using NodeJS, we suggest you use our NodeJS SDK instead.
The first thing to use the Admin API is to authenticate your requests.
To do so, you have to include your secret key in a header named X-PluginLab-Admin-Sdk-Secret and your plugin id in a header named X-PluginLab-Plugin-Id.
Here is an example with curl:
Here is a Nodejs example using the axios library:
We show you how to generate a secret in the next section
If you plan to use our RESTful API, it means you will probably need to verify the user access token sent by PluginLab at some point.
If you need to verify the access token, please check the Verifying PluginLab Tokens section first.
The API makes it possible to query all the members associated to your plugin.
Query example
Query parameters
- limit: a number between 1 and 50
- startAfter: a pagination cursor or null for the first request
Response example
Query example
Url parameters
- memberId: the member id
Response example
Query example
Url parameters
- memberEmail: the member email
Response example
When a member logs in using a third-party auth provider, the latter generates an access token and optionally a refresh token that the application can use
to interact with the third-party service on behalf of the user.
PluginLab allows you to get the identities that have been generated when the user logged in:
The response can be an empty JSON object if the user has no identity {}.
Otherwise it will be a json with the following type:
For OAuth providers such as Google or Gitlab the access token has a limited lifetime. PluginLab provides an endpoint in case your token needs to be refreshed.
The following endpoint will refresh the token
Where <PROVIDER_ID> can be either google or gitlab at this moment.
This endpoint will return the identity with fresh tokens as follows:
Note this endpoint currently works only with google and gitlab. Github does not provide any refresh token at this moment. If you need support for more providers feel free to reach out.
Sometimes it's possible that the refresh token is revoked or expired. In that case PluginLab will not be able to refresh the token anymore.
In that situation, PluginLab will return the following error with a HTTP CODE 422:
The PluginLab API allows you to create a member with an email and a password.
When you use the create member endpoint, the default sign-in method will be email-and-password.
Note this sign-in method is not currently supported by the auth portal. However, email-and-password based members are compatible with Google and Passwordless email sign-in.
You will notice that a use who has a password, has a hashConfig object that defines the algorithm associated with the hashed password. This will allow you to export your users in the future if you need to.
Query example
Response example
Developers can update any member by making a PATCH request to the member's endpoint with the corresponding member id.
The API allows you to patch any user by id. You can pass any or all the following parameters as part of your JSON body request:
- name
- givenName
- familyName
- pictureUrl
- metadata: an object containing any key:value pair
Query example
Response example
Developers can delete a user by making a DELETE request to the API member's enpdoint with the corresponding member id.
Example query
In all cases, the response will be an HTTP Code 200.
Thanks to this API you can manage your members and do some daily operations such as fetching users, updating them and more.
Note: this guide is describing how to use our RESTful API. If you are looking to implement it using NodeJS, we suggest you use our NodeJS SDK instead.
Authenticating your requests
The first thing to use the Admin API is to authenticate your requests.
To do so, you have to include your secret key in a header named X-PluginLab-Admin-Sdk-Secret and your plugin id in a header named X-PluginLab-Plugin-Id.
Here is an example with curl:
curl --location --request GET 'https://auth.pluginlab.ai/admin/plugins/5e3a84b73822f193bd23be935cc5b3d5/members?limit=50' \
--header 'X-PluginLab-Plugin-Id: 5e3a84b73822f193bd23be935cc5b3d5' \
--header 'X-PluginLab-Admin-Sdk-Secret: ca4424c3d050878b67c208953efca2391324571be7738279a19e2c59bc3e6b97'Here is a Nodejs example using the axios library:
const httpClient = axios.create({
baseURL: "https://auth.pluginlab.ai/admin/plugins/<PLUGIN_ID>/<PATH>",
headers: {
'X-PluginLab-Admin-Sdk-Secret': <YOUR_SECRET_KEY>,
'X-PluginLab-Plugin-Id': <PLUGIN_ID>,
},
});We show you how to generate a secret in the next section
Verifying user's token
If you plan to use our RESTful API, it means you will probably need to verify the user access token sent by PluginLab at some point.
If you need to verify the access token, please check the Verifying PluginLab Tokens section first.
Getting members
The API makes it possible to query all the members associated to your plugin.
Query example
curl "https://auth.pluginlab.ai/admin/plugins/<PLUGIN_ID>/members?limit=50&startAfter=<cursor_id>"Query parameters
- limit: a number between 1 and 50
- startAfter: a pagination cursor or null for the first request
Response example
{
"items": [
{
"metadata": {},
"auth": {
"isVerified": true,
"hasPassword": false,
"providerUserId": "118153666269841543273",
"email": "kevin@gmail.com",
"signInMethod": "google"
},
"createdAtMs": 1685903928798,
"updatedAtMs": 1685903928798,
"customFields": {},
"givenName": "Kevin",
"familyName": "Piacentini",
"pictureUrl": "https://lh3.googleusercontent.com/a/AAcHTtcO2sFJZAoGjlCl3sVpfUqOZjfJeXEg5WjHa2s_ow=s96-c",
"name": "Kevin Piacentini",
"id": "mem_ce105066572deefcdd2d520220661defe6ed40a4",
"updatedAtTs": {
"_seconds": 1685903928,
"_nanoseconds": 798000000
},
"createdAtTs": {
"_seconds": 1685903928,
"_nanoseconds": 798000000
}
}
],
"total": 1,
"nextPageToken": "mem_ce105066572deefcdd2d520220661defe6ed40a4"
}Getting a member by id
Query example
curl --location --request GET 'https://auth.pluginlab.ai/admin/plugins/<PLUGIN_ID>/members/<MEMBER_ID>'Url parameters
- memberId: the member id
Response example
{
"metadata": {},
"auth": {
"isVerified": true,
"hasPassword": false,
"providerUserId": "118153666269841543273",
"email": "kevin@gmail.com",
"signInMethod": "google"
},
"createdAtMs": 1685903928798,
"updatedAtMs": 1685903928798,
"customFields": {},
"givenName": "Kevin",
"familyName": "Piacentini",
"pictureUrl": "https://lh3.googleusercontent.com/a/AAcHTtcO2sFJZAoGjlCl3sVpfUqOZjfJeXEg5WjHa2s_ow=s96-c",
"name": "Kevin Piacentini",
"id": "mem_ce105066572deefcdd2d520220661defe6ed40a4"
}Getting a member by email
Query example
curl --location --request GET 'https://auth.pluginlab.ai/admin/plugins/<PLUGIN_ID>/member/byEmail/<MEMBER_EMAIL>'Url parameters
- memberEmail: the member email
Response example
{
"metadata": {},
"auth": {
"isVerified": true,
"hasPassword": false,
"providerUserId": "118153666269841543273",
"email": "kevin@gmail.com",
"signInMethod": "google"
},
"createdAtMs": 1685903928798,
"updatedAtMs": 1685903928798,
"customFields": {},
"givenName": "Kevin",
"familyName": "Piacentini",
"pictureUrl": "https://lh3.googleusercontent.com/a/AAcHTtcO2sFJZAoGjlCl3sVpfUqOZjfJeXEg5WjHa2s_ow=s96-c",
"name": "Kevin Piacentini",
"id": "mem_ce105066572deefcdd2d520220661defe6ed40a4"
}Get member's identities
When a member logs in using a third-party auth provider, the latter generates an access token and optionally a refresh token that the application can use
to interact with the third-party service on behalf of the user.
PluginLab allows you to get the identities that have been generated when the user logged in:
curl --location 'https://auth.pluginlab.ai/admin/plugins/<PLUGIN_ID>/members/<MEMBER_ID>/identitiesThe response can be an empty JSON object if the user has no identity {}.
Otherwise it will be a json with the following type:
{
"gitlab": {
"providerUserId": "1939238",
"provider": "gitlab",
"accessToken": "aa9fxxxxxxxxxxxxxxxxx20e274",
"accessTokenExpiresAtMs": 1692295729026,
"refreshTokenExpiresAtMs": null,
"refreshToken": "760a4xxxxxxxxxxxdede2530aef0b5",
"lastUsedAtMs": 1692288529026
}
}Refresh identity access token
For OAuth providers such as Google or Gitlab the access token has a limited lifetime. PluginLab provides an endpoint in case your token needs to be refreshed.
The following endpoint will refresh the token
curl --location --request POST 'https://auth.pluginlab.ai/admin/plugins/<PLUGIN_ID>/members/<MEMBER_ID>/identities/<PROVIDER_ID>/refresh'Where <PROVIDER_ID> can be either google or gitlab at this moment.
This endpoint will return the identity with fresh tokens as follows:
Note this endpoint currently works only with google and gitlab. Github does not provide any refresh token at this moment. If you need support for more providers feel free to reach out.
{
"providerUserId": "1939238",
"provider": "gitlab",
"accessToken": "aa9fxxxxxxxxxxxxxxxxx20e274",
"accessTokenExpiresAtMs": 1692295729026,
"refreshTokenExpiresAtMs": null,
"refreshToken": "760a4xxxxxxxxxxxdede2530aef0b5",
"lastUsedAtMs": 1692288529026
}Handling refresh errors
Sometimes it's possible that the refresh token is revoked or expired. In that case PluginLab will not be able to refresh the token anymore.
In that situation, PluginLab will return the following error with a HTTP CODE 422:
{
"code": "refresh-token-failed",
"message": "The refresh token request has been rejected by the provider. It most likely means the refresh token is expired. Please ask your user to sign-in again using your auth-portal url."
}Creating a member
The PluginLab API allows you to create a member with an email and a password.
When you use the create member endpoint, the default sign-in method will be email-and-password.
Note this sign-in method is not currently supported by the auth portal. However, email-and-password based members are compatible with Google and Passwordless email sign-in.
You will notice that a use who has a password, has a hashConfig object that defines the algorithm associated with the hashed password. This will allow you to export your users in the future if you need to.
Query example
curl --location --request POST 'https://auth.pluginlab.ai/admin/plugins/b901b113ecf933b2a448f0fcb26267d9/members' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "kevin@pluginlab.ai",
"password": "C02@dqwedqwe"
"isVerified": true
}'Response example
{
"id": "mem_a5bc95522344c5c065ac4a02dc6dfdb4e438943f",
"auth": {
"isVerified": false,
"email": "kevin@pluginlab.ai",
"hasPassword": true,
"signInMethod": "email-and-password",
"passwordHash": "dba6902e9de89af59eb9c06bb1e494e40a0243a1585922bc45373f42deffcfaa",
"passwordHashConfig": {
"algorithm": "scrypt",
"memCost": 16384,
"keyLength": 32,
"salt": "2bc4f159a9250632982af37469fedbef"
}
},
"customFields": {},
"metadata": {},
"createdAtMs": 1686085947830,
"updatedAtMs": 1686085947830
}Updating a member
Developers can update any member by making a PATCH request to the member's endpoint with the corresponding member id.
The API allows you to patch any user by id. You can pass any or all the following parameters as part of your JSON body request:
- name
- givenName
- familyName
- pictureUrl
- metadata: an object containing any key:value pair
Query example
curl --location --request PATCH 'https://auth.pluginlab.ai/admin/plugins/<PLUGIN_ID>/members/<MEMBER_ID>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Kevin Piacentini",
"givenName": "Kevin",
"familyName": "Piacentini",
"pictureUrl": "https://lh3.googleusercontent.com/a/AAcHTtcO2sFJZAoGjlCl3sVpfUqOZjfJeXEg5WjHa2s_ow=s96-c",
"metadata": {
"something": "Any additional info you wanna store"
}
}'Response example
{
"auth": {
"isVerified": true,
"hasPassword": false,
"providerUserId": "118153666269841543273",
"email": "kevin@gmail.com",
"signInMethod": "google"
},
"createdAtMs": 1685903928798,
"customFields": {},
"givenName": "Kevin",
"familyName": "Piacentini",
"name": "Kevin Piacentini",
"id": "mem_ce105066572deefcdd2d520220661defe6ed40a4",
"metadata": {
"something": "Any additional info you wanna store"
},
"updatedAtMs": 1686073922184,
"pictureUrl": "https://lh3.googleusercontent.com/a/AAcHTtcO2sFJZAoGjlCl3sVpfUqOZjfJeXEg5WjHa2s_ow=s96-c"
}Deleting a member
Developers can delete a user by making a DELETE request to the API member's enpdoint with the corresponding member id.
Example query
curl --location --request DELETE 'https://auth.pluginlab.ai/admin/plugins/5e3a84b73822f193bd23be935cc5b3d5/members/mem_ce105066572deefcdd2d520220661defe6ed40a4'In all cases, the response will be an HTTP Code 200.
Updated on: 17/08/2023
Thank you!