Creating your own SSO integration
We have a WordPress SSO (single sign-on) plugin and support for SAML (Security Assertion Markup Language) SSO; however, you may be using different technologies and want to build your own integration. This is possible with our API.
When a user on your platform wants to sign into Good Grants the first thing you’ll need to do is check whether they already exist in Good Grants.
Get user by email
Using the Get user by email endpoint you can check whether the user exists by passing their email address to Good Grants. If this endpoint returns empty then you’ll need to create the user in Good Grants. If the user does exist then this endpoint will return the slug which you can use to generate an auth token.
https://api.awardsplatform.com/user/:email
Here’s an example response you’ll get if the user does exist (the slug, which you'll need for the next step is highlighted below in bold) -
{
"analytics_cookies": false,
"broadcast_emails": false,
"confirmed_at": "2020-01-01T00:00:00Z",
"created_at": "2020-01-01T00:00:00Z",
"email": "no-reply@awardforce.com",
"first_name": "Test",
"last_name": "Name",
"marketing_cookies": false,
"mobile": "+393216549873",
"name": "Test Name",
"necessary_cookies": false,
"notification_emails": false,
"notification_sms": false,
"preferences": {
"broadcast_emails": false,
"notification_emails": false,
"notification_sms": false
},
"roles": [
{
"slug": "OkvJXMNd",
"link": "https://api.awardsplatform.com/role/OkvJXMNd",
"name": {
"en_GB": "Role name"
}
}
],
"slug": "EnDNqjlb",
"social_sharing": false,
"updated": "2020-01-01T00:00:00Z",
"user_fields": [
{
"slug": "ErApVaqk",
"link": "https://api.awardsplatform.com/field/ErApVaqk",
"label": {
"en_GB": "Field label"
},
"value": "Field value"
}
]
}
Get auth token
Once you’ve got the user slug you can request an auth token by making a request to the Get auth token endpoint.
https://api.awardsplatform.com/user/:slug/auth-token
This will return a unique token you can use to sign the user into Good Grants. The example response -
{
"auth_token": "sKBO8pXpyd2R5FPssDP3CePlmH5OVTxj"
}
Once you’ve got the token you can redirect the user to the following URL to automatically sign them in -
https://[ACCOUNT_DOMAIN]/login?token=[TOKEN]
Create user
If the user doesn’t already exist on the program you can use the Create user endpoint to create an account for them. You will need to submit a first name, last name, email address, and password as a minimum.
The request is made to -
https://api.awardsplatform.com/user
An example body -
{
"first_name": "Test",
"last_name": "Name",
"email": "no-reply@awardforce.com",
"password": "123456789123",
"mobile": "+393216549873",
"roles": ["OkvJXMNd"],
"preferences":
{
"broadcast_emails": false,
"notification_emails": false,
"notification_sms": false
},
"user_fields":
{
"QVgKEqXR": "Field value"
}
}'
The user's slug will be included in the response header which you can then use to generate an auth token.
For more information about our API, please refer to our API documentation.
