Magic Link (SSO)

Retrieve a secure, one-time URL that will automatically login an affiliate to their dashboard.

Use this endpoint to generate a secure, one-time URL that you can display to affiliates or redirect them to in order to have them automatically logged into their Rewardful dashboard without requiring them to provide their email and password.

Links expire after one minute and cannot be used more than once. Generating a new magic link will invalidate all previous magic links for that affiliate, even if they haven't been used.

Usage

Because magic links expire after one minute you should not insert them into HTML documents. If you do, it's possible that the link will have expired by the time the affiliates clicks it.

Instead, you should fetch magic links from Rewardful on-demand and immediately redirect the affiliate to the magic link returned by the Rewardful REST API.

The diagram below illustrates this flow:

1. An authenticated user clicks a "View affiliate dashboard" link that leads to an app.example.com/rewardful URL in your application.

2. Your application requests a magic link for the affiliate from the Rewardful REST API.

3. The Rewardful REST API returns the magic link to your application.

4. Your application redirects the user to the Rewardful magic link.

The flow in Ruby pseudocode (using HTTParty to make network requests) might look something like this:

require 'httparty'

get '/rewardful' do
  response = HTTParty.get(
    "https://api.getrewardful.com/v1/affiliates/#{current_user.affiliate_id}/sso",
    basic_auth: { username: ENV['REWARDFUL_API_SECRET'] }
  )

  magic_link = response.parsed_response.dig('sso', 'url')

  redirect_to magic_link
end

Request

Method	URL
GET	https://api.getrewardful.com/v1/affiliates/:id/sso

Example

curl --request GET \
  --url https://api.getrewardful.com/v1/affiliates/d049c0c6-5caf-440e-a774-8d5e87086d0b/sso \
  -u YOUR_API_SECRET:

Response

Success

Response code	Body
200	Data about the SSO URL and brief affiliate summary.

{
  "sso": {
    "url": "https://affiliates.example.com/sso?token=eyJhbGciOiJIUzI1NiJ9",
    "expires": "2020-08-28T05:32:02.471Z"
  },
  "affiliate": {
    "id": "d049c0c6-5caf-440e-a774-8d5e87086d0b",
    "email": "[e-mail]"
  }
}

Failure

Not found

Response code	Body
404	JSON object describing the error.

{  "error": "Affiliate not found: " }

Authentication failure

Response code	Body
401	Description of the authentication failure.

{  "error": "Invalid API Secret." }