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:
response_type
- The stringcode
client_id
- Your custom app's client ID, found in the Memberful dashboardstate
- 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 (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:
grant_type
- This exact string:authorization_code
client_id
- Your custom app's client IDclient_secret
- Your custom app's client secret (Only required 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.
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:
code_challenge
- The code challenge you generatedcode_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
- This exact string:refresh_token
client_id
- Your custom app's client IDclient_secret
- Your custom app's client secret (Only required for server-side applications. Mobile and single-page applications can skip this parameter.)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.
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: