Signing members in with OAuth 2.0

Memberful supports the OAuth 2.0 protocol for authentication. You can use this to sign members in to your external application.

The OAuth 2.0 authorization flow

When your application wants to force a member to sign in, redirect them to Memberful's authorization endpoint, which will ensure the member is signed in, before sending them back to your application's redirect_url (see below) with an authorization code.

The authorization code has a lifetime of 1 minute. During that 1 minute window your application can send it to Memberful in exchange for an access_token. The access_token is active for 15 minutes, and allows your application to communicate with Memberful on the member's behalf.

This process requires your application and Memberful know the following information:

• client_id This is a unique identifier for your site, and should be included in the URL when you send a member to Memberful for authentication.
• client_secret This value is a secret known only to your application and Memberful. It should never be stored in a place a member might be able to access it (e.g. in URLS, sessions, or a cookie).
• redirect_url This is where Memberful sends members after they sign in. The authorization code will be provided in a query string parameter named code.

You can create these values by setting up a new "Custom Application" in your admin panel (Settings → Integrate → Custom Applications).

During authentication send these requests to the following URLS:

• Authorization endpoint (ensures the member is signed in, and sends them back to your application): https://yoursite.memberful.com/oauth?client_id=XXXX

• Tokens endpoint: https://yoursite.memberful.com/oauth/token

Implementing the authorization code flow

First, redirect the member to the following URL:

https://{subdomain}.memberful.com/oauth?client_id={application identifier}&response_type=code

This will prompt the member to sign in, and then send them back to the redirect URL you specified when setting up the custom application.

The redirect url will include an extra parameter, code. This code's sole purpose is to be exchanged for an access token (which you can use to fetch a member's account details), and cannot be used for any other purpose. To exchange the code for the token, POST the following parameters to the token endpoint URL:

• client_id - The identifier of the application, from the Admin panel.
• client_secret - The application's shared secret, also from the Admin panel.
• grant_type - This must always be the string authorization_code.
• code - This is the value that was passed to your site via the OAuth redirect mentioned above.

You'll receive a payload that looks like this:

{
  "access_token": "...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "..."
}

Now you can use the access_token as described below in Signing members in.

Signing members in

Once you've acquired an access token, you can make a GET request to the Memberful GraphQL API endpoint to get information about the member:

https://yoursite.memberful.com/api/graphql/member?access_token=XXX&query=graphql_query

This endpoint has a single field called currentMember with GraphQL type Member. You have to specify what information you need in the query parameter.

Example query:

{
  currentMember {
    address {
      city
      street
      postalCode
      country
    }
    creditCard {
      expMonth
      expYear
    }
    customField
    downloads {
      id
      name
    }
    email
    fullName
    id
    phoneNumber
    subscriptions {
      active
      expiresAt
      plan {
        id
        name
      }
    }
    unrestrictedAccess
  }
}

Example response:

{
  "data": {
    "currentMember": {
      "address": {
        "city": null,
        "street": null,
        "postalCode": null,
        "country": null
      },
      "creditCard": {
        "expMonth": 10,
        "expYear": 2020
      },
      "customField": "",
      "downloads": [
        {
          "id": "1",
          "name": "A download"
        }
      ],
      "email": "john.doe@example.com",
      "fullName": "John Doe",
      "id": "1",
      "phoneNumber": null,
      "subscriptions": [
        {
          "active": true,
          "expiresAt": 1528625190,
          "plan": {
            "id": "1",
            "name": "Monthly"
          }
        }
      ],
      "unrestrictedAccess": false
    }
  }
}

Please check our API explorer to learn more about the available GraphQL types.