Sign members into apps via OAuth 2.0

Memberful supports the OAuth 2.0 protocol for authentication, which means that you can use Memberful as the sign-in mechanism for your custom applications, including both web and mobile apps.

Members sign in to your app or website via Memberful's sign-in process. Once we've confirmed they're signed in, your app can pull the member's data from our API.

In this help doc:

Application types

When you create an OAuth application (Settings → Custom applications), you'll choose from one of three application types: Server-side, Single-page, and Mobile.

Server-side application

This application type requires that your application is able to securely store a private client_secret. You'll be provided with a client_id and client_secret.

Single-page application

Single-page applications can't secure a client secret, so one is not generated or required. These applications must provide Proof Key of Code Exchange parameters described below.

Mobile applications

Like single-page applications, mobile and native apps do not use a client secret and must provide Proof Key of Code Exchange parameters. Mobile applications may use a private URI scheme or claimed "https" scheme as the redirect URI.

The OAuth standard best practice recommends that private URI schemes match a domain you control, in reverse, such as com.example.app if your domain is app.example.com.

Obtaining an access token

To sign a member in, your application must obtain an access token using the OAuth 2.0 Authorization Code flow. Access tokens grant access to a member's data, including their name, email, and subscriptions.

The flow is similar for all application types, but single-page and mobile applications must provide Proof Key of Code Exchange (PKCE) parameters instead of a client secret.

We recommend using an OAuth 2.0 library to obtain an access token.

Our OAuth 2.0 endpoint doesn't require scope. Therefore you can provide any scope, but it will be ignored.

Requesting an authorization code

Your application must open this Memberful URL in a browser:

https://YOURSITE.memberful.com/oauth

If you open this as a POST request instead of opening it in a browser, an error message will be returned.

The request must include these parameters:

Memberful will prompt the member to enter their email in the browser. Once they’re signed in, Memberful will call the redirect URI provided when you created the custom application (unless you've set up a custom sign in / out app). We’ll also add the code and state parameters to the redirect URI. For example:

https://example.com/oauth_callback?code=[CODE]&state=[STATE]

Requesting an access token

When your app receives the redirect, it must verify that the state parameter matches the state generated for the authorization request. Then, it can exchange the authorization code for an access token by sending a POST request to:

https://YOURSITE.memberful.com/oauth/token

The request must include these parameters:

In response, Memberful will return an access token:

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

Authorization codes are only valid for 1 minute and can only be used once.

Proof Key of Code Exchange (PKCE)

PKCE is an extension to the above flow for single-page and mobile applications. Your client app will issue the two requests above with some differences.

Before requesting an authorization code, your app must generate a code verifier and code challenge. The code verifier must be a secure random string between 43 and 128 characters long. If the client device can generate a SHA256 hash, the code challenge must be a Base64-URL encoded SHA256 hash of the code verifier. If not, the code verifier may be used as the challenge.

Base64 and Base64-URL are different standards. If you use regular Base64 encoding, you'll frequently run into fatal errors. Make sure you use Base64-URL encoding to avoid these issues.

Example pseudo code for generating code challenge:

code_verifier  = generate_random_string(128)
sha256_hash    = sha256(code_verifier)
code_challenge = base64url_encode(sha256_hash)

Your application must store the code verifier to use it later, when requesting an access token. Then, include these two parameters in the authorization code request:

When your app subsequently receives the redirect request, verify the state and include this parameter in the access token request, instead of the client_secret:

In response, Memberful will return an access token.

Refreshing access tokens

Access tokens are valid for 15 minutes. You can use a refresh token (provided with each access token) to get a new access token. Refresh tokens are valid for one year.

To obtain a new access token, send a POST request to:

https://YOURSITE.memberful.com/oauth/token

The request must include these parameters:

In response, Memberful will return an access token.

Requesting member data

Once your application has an access token, it can request data from Memberful's GraphQL API to retrieve information about the member.

Keep in mind that this should be a GET Request, not POST.

Endpoint URL:

https://YOURSITE.memberful.com/api/graphql/member?query=GRAPHQL_QUERY

Authorization header:

Authorization: Bearer <access-token>

This GraphQL 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
    }
    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
      },
      "downloads": [
        {
          "id": "1",
          "name": "A download"
        }
      ],
      "email": "[email protected]",
      "fullName": "John Doe",
      "id": "1",
      "phoneNumber": null,
      "subscriptions": [
        {
          "active": true,
          "expiresAt": 1528625190,
          "plan": {
            "id": "1",
            "name": "Monthly"
          }
        }
      ],
      "unrestrictedAccess": false
    }
  }
}

See the API explorer to learn more about the available GraphQL types.

Automatic sign in and sign out

You can set your OAuth application as your login application (Settings → Custom applications → Automatic login) and we will automatically sign members into your application any time they sign in to Memberful.

This option will only show up if you've configured a custom app with OAuth and you aren't using our WordPress plugin, since WordPress becomes your login application automatically when you've enabled the plugin.

If you've set up automatic login for a custom app (let's call this App A) and a sign-in is initiated through a different OAuth application (we'll call this App B), Memberful will ignore App B's Redirect URL, and instead redirect to App A's Redirect URL, because it's the default login application. However, Memberful will append a redirect_to query parameter to the URL, so that App A can redirect to the desired URL after signing in.

Sign out

When a member signs out from Memberful and you've set up an application for automatic sign in / out as described above, we automatically redirect the member to that application's redirect URL with an additional parameter of action set to logout. Your application can use this to detect the logout action, then sign the member out and redirect them back to the sign-in form or some other page of your choosing.

Related help docs:

Can't find what you're looking for? We'd love to help! 💪

Send us a message through the orange chat bubble in the lower right corner of the page. You'll hear back within a few hours Monday - Friday. 😀