Signing members in with OAuth 2.0

Memberful supports the OAuth 2.0 protocol for authentication. Your custom applications, including both web and mobile apps, can use Memberful's OAuth provider to sign members in.

In this help doc:

Application types

When you create an OAuth application (Settings → Integrate → Custom Apps), 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.

Requesting an authorization code

Your application must open this Memberful URL in a browser:

https://YOURSITE.memberful.com/oauth

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. 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.

Example pseudo code for generating code challenge:

code_verifier  = generate_random_string(128)
sha256_hash    = sha256(code_verifier)
code_challenge = base64_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.

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
    }
    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
    }
  }
}

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 → Integrate → Custom Apps → Automatic login) and we will automatically sign members into your application when they sign in to Memberful.

Sign out

When a member signs out from Memberful and we detect a login application, we automatically redirect the member to the application's redirect URL with an additional parameter of action set to logout. Your application can use this to detect the logout action and sign the member out.

Recent changes

Memberful no longer supports the OAuth password grant type for new applications. See our transition guide to learn how to upgrade existing apps that use this grant type.

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. 😀