# Magic Link (SSO)

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.

![](https://3715955084-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M8QpBSEENVQIIrPkS3u%2F-MFw9UUjfhUpli7ORP8k%2F-MFwG4vHaGSYMSBmsnNU%2Fimage.png?alt=media\&token=9183fe51-2822-489c-baf0-2d668792c276)

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

```ruby
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

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

Response

{% tabs %}
{% tab title="Success" %}

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

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

{% endtab %}

{% tab title="Failure" %}

### Not found

| Response code | Body                              |
| ------------- | --------------------------------- |
| `404`         | JSON object describing the error. |

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

### Authentication failure

| Response code | Body                                       |
| ------------- | ------------------------------------------ |
| `401`         | Description of the authentication failure. |

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

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.rewardful.com/rest-api/affiliates/sso.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.