Iron Plans
Search…
Creating customer tokens

TL;DR

Iron Plans' needs to keep track of your customers to manage their Teams, Plan, and Billing. To do this we use Customer Tokens. A Customer Token is an expiring JWT signed by Iron Plans that identifies and authorizes a Customer.
Customers are created automatically every time your service retrieves a Customer Token with a new customer_source_idand customer_email.
Iron Plans supports creating customer tokens via 1st party auth or 3rd party auth. See deep dive for an in-depth guide on how they work.
Example generating Customer Tokens in Python (1st party auth)
1
def get_ironplans_customer_token(user):
2
r = requests.post(
3
"https://api.ironplans.com/customers/v1/token/",
4
data={"customer_source_id": user.id, "customer_email": user.email},
5
headers={"Authorization": "Bearer my-private-token"}
6
).json()
7
return r["token"]
Copied!

Deep Dive

Customers are created automatically every time your service retrieves a Customer Token with a new customer_source_id . A Customer Token is an expiring JWT signed by Iron Plans that identifies and authorizes a Customer to manage their Teams, Plan, and Billing.
Email us at [email protected] if you want to bulk add existing users or migrate teams.
You use one of two flows for creating customer tokens, depending on how you perform user authentication in your app:
  • 1st Party Auth. You own the authentication flow, and have a backend API that can authenticate your users.
  • 3rd Party Auth. You delegate authentication to a 3rd party, such as Auth0 or Firebase Auth, and get an ID token back that identifies a user.

1st Party Auth

1st-party authenticated Customer Tokens using SSR
In 1st-party authentication, you create a Customer Token using a Private Token from a secure environment where you can access secrets.
The token can also be safely cached per-user in your service until the JWT expires.
The following API call will create a Customer Token, automatically creating a Customer account if one does not already exist.
post
https://api.ironplans.com/customers/v1/token
Create Customer Token

SSR flow

Call /customers/v1/token after you've authenticated the user for every page that needs Customer information (most likely all of them). The token returned should be made available to the Client-side SDK init function however your backend framework handles rendering.

SPA flow

Add an endpoint to your API that will return a Customer Token, e.g. POST /ip/customers-token . It doesn't need to accept any parameters. The response must include the token returned from /customers/v1/token .
If you reuse an existing endpoint, it should be called as early as possible to make sure the Customer SDK can load customer information quickly.

3rd Party Auth

With 3rd-party auth, the entire flow is handled client-side.
See below for how to get OIDC_ID_TOKEN for your auth provider.
Example 3rd-party authenticated Customer Tokens
Email [email protected] with requests for an OIDC-compliant auth providers not listed here.

Init Customer SDK

Using the Public Token you created earlier, initialize the Customer client-side as early in the page's lifecycle as possible:
1
import Customer from '@ironplans/browser'
2
3
const customer = await Customer.init({
4
// either: 1st-party auth
5
token,
6
// or: 3rd-party auth
7
publicToken,
8
idToken,
9
})
Copied!
You did it! Add buttons to trigger the built-in Widgets, or build your own UI

Using Cognito Auth

In your dashboard settings, set Cognito as your Auth Issuer.
Go to integrations and input your AWS region, user pool ID, and app client ID.
This information should be in your AWS Cognito console after you select your user pool: https://console.aws.amazon.com/cognito/v2
Iron Plans uses this information to verify the ID token's audience and issuer claims before issuing a Customer Token for the token's sub .
Get a token from your Cognito user - here's a React example:
1
import * as AmazonCognitoIdentity from "amazon-cognito-identity-js";
2
3
const poolData = {UserPoolId: "USER_POOL_ID", ClientId: "CLIENT_ID"};
4
const userPool = new AmazonCognitoIdentity.CognitoUserPool(poolData);
5
6
const cognitoUser = userPool.getCurrentUser()
7
let idToken
8
if (cognitoUser != null) {
9
cognitoUser.getSession((err, session) => {
10
if (err) {
11
console.error(err)
12
} else if (!session.isValid()) {
13
console.error("Invalid session.")
14
} else {
15
idToken = session.getIdToken().getJwtToken()
16
}
17
})
18
}
Copied!
You should then be able to use this Cognito token to initialize a customer in Iron Plans.
1
const customer = await Customer.init({
2
publicToken, // generated from Iron Plans Dashboard
3
idToken,
4
)
Copied!

Using Firebase Auth

Enable Firebase Auth in your Provider's settings and set projectId to your Firebase project ID. https://console.firebase.google.com/project/YOUR-PROJECT-ID
Iron Plans verifies the ID token's audience and issuer claims using the projectId configured before issuing a Customer Token for the token's sub .
Get an ID token from your firebase user:
1
// For example:
2
const { user } = await signInWithEmailAndPassword(auth, email, passwd)
3
const idToken = await user.getIdToken()
Copied!