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 Award Force the first thing you’ll need to do is check whether they already exist in Award Force.

Get user by email 

Using the Get user by email endpoint you can check whether the user exists by passing their email address to Award Force. If this endpoint returns empty then you’ll need to create the user in Award Force. If the user does exist then this endpoint will return the slug which you can use to generate an auth token.

https://api.cr4ce.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.cr4ce.com/user/:slug/auth-token

This will return a unique token you can use to sign the user into Award Force. 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.cr4ce.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.

 

 

Need more help? Get in touch!

We're here to help if you need it. Simply get in touch with our Client Success team through one of the methods available at the base of the page.