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:
response_type
- The stringcode
.client_id
- Your custom app's client ID, found in the Memberful dashboard.state
- A random string generated by your application, which you’ll verify later.
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:
grant_type
- The stringauthorization_code
.client_id
- Your custom app's client ID.client_secret
- Your custom app's client secret, for server-side applications. (See below for other application types.)code
- The authorizationcode
included in the redirect.
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:
code_challenge
- The code challenge you generated.code_challenge_method
-S256
if SHA256 was used, orplain
if not.
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
:
code_verifier
- The code verifier you generated.
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:
grant_type
- The stringrefresh_token
.client_id
- Your custom app's client ID.client_secret
- Your custom app's client secret, for server-side applications.refresh_token
- The refresh token received with an access token.
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.