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.

In this help doc:

• OAuth application types
• Supported OAuth grants
• Signing members in
• Automatic sign in and sign out

OAuth application types

When you create an OAuth application (Settings → Integrate → Custom Applications), you'll choose from one of three application types: Server-side, Single Page, and Mobile. Each application type has access to all supported Memberful OAuth grants, but each has slightly different permissions.

Server-side Application

This is the default application type. You'll be provided with client_id and client_secret and you will have to use client_secret in all token requests.

Single Page Application

Single Page Applications can't store client secrets securely, so we do not provide a client secret, nor do we require it when you make token requests. Do not use this application type for server-side applications.

Mobile Application

Like Single Page Applications, we do not provide or require a client secret. However, we do require Proof Key of Code Exchange for the authorization code grant. We also allow you to use non-HTTP redirects for Mobile Applications (e.g. appname://oauth_callback).

Supported OAuth grants

If you want to sign a member in, first obtain an access token via an OAuth 2.0 grant. This will allow you to access member data on their behalf. We support three different OAuth 2.0 grants:

Authorization code grant

Redirect a member to Memberful's authorization URL:

https://YOURSITE.memberful.com/oauth?client_id=APPLICATION_IDENTIFIER&response_type=code&state=STATE

With the following parameters:

• client_id - The identifier of the application, from the Memberful dashboard.
• response_type - This must be the string code.
• state (optional) - A random string sent back to you via the redirect URL.

Once we verify that the member is signed in, we redirect them to the redirect URL you provided when you created Custom Application. We will also add the code and state parameters to the URL:

https://example.com/oauth_callback?code=AUTHORIZATION_CODE&state=STATE

You can use the state parameter to associate the response with the initial request. Then, you can use the authorization code and exchange it for an access token by sending a POST request to:

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

With the following parameters:

• client_id - The identifier of the application, from the Memberful dashboard.
• client_secret - The application's shared secret, also from the Memberful dashboard (only required for Server-side Applications).
• grant_type - This must be the string authorization_code.
• code - Passed to your site via the OAuth redirect mentioned above.

You'll receive an access token payload in the response:

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

Proof Key of Code Exchange (PKCE)

Mobile applications can't securely store their OAuth secret so we do not require it during token requests. However, to ensure the security of the authorization codes, we require Proof Key of Code Exchange for mobile applications.

To use PKCE, you'll need to generate a code verifier during the authorization request and save it locally in your application. Once the member is redirected back to your application with an authorization code, use the code verifier for the access token exchange.

Code verifier is a cryptographically random string between 43 and 128 characters long. Once you generate the code verifier, use it to generate a code challenge. This is a BASE64-URL-encoded string of the SHA256 hash of the code verifier. If you can't use SHA256 hash in your application, then you are permitted to use the plain code verifier string as the challenge.

Example pseudo code for generating code challenge:

code_verifier = generate_random_string(128)
sha256_hash   = sha256(code_verifier)
code_challege = base64_encode(sha256_hash)

Once you have the code challenge, you should use two additional parameters when redirecting members to the OAuth authorization URL:

• code_challenge - Code challenge generated as explained above.
• code_challenge_method - Use S256 if you used SHA256 to generated the code challenge or plain if you are using the plain code verifier as the code challenge.

When you obtain an authorization code, you have to use the code_verifier parameter containing the code verifier when exchanging the code for an access token.

Refresh token grant

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

In order to get a new access token send a POST request to:

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

With the following parameters:

• client_id - The identifier of the application, from the Memberful dashboard.
• client_secret - The application's shared secret, also from the Memberful dashboard (only required for Server-side Applications).
• grant_type - This must be the string refresh_token.
• refresh_token - Refresh token provided with an access token.

You'll receive an access token payload in the response:

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

Password grant

If you have a mobile application, you may want to sign members in directly from your app by asking them for their email and password. When they provide it to you, you can exchange it for an access token.

Send a POST request to:

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

With the following parameters:

• client_id - The identifier of the application, from the Memberful dashboard.
• client_secret - The application's shared secret, also from the Memberful dashboard (only required for Server-side Applications).
• grant_type - This must be the string password.
• username - Member's email address.
• password - Member's password.

You'll receive an access token payload in the response:

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

Signing members in

Once you've acquired an access token, make a GET request to the Memberful GraphQL API endpoint 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 Applications → 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.