Logto role / organization

Grants the buyer an identity-level role (or organization membership) inside your Logto tenant. Useful for token-gating pages on your own apps that already use Logto as their auth provider.

What it does

When an order is paid, the glue calls the Logto Management API:

• logto_role entitlement → POST /api/users/{userId}/roles with the configured role ID.
• logto_organization entitlement → POST /api/organizations/{orgId}/users (+ optional POST /api/organizations/{orgId}/users/{userId}/roles if roleId is set).

The buyer's Logto user ID is known because they sign in via the same Logto tenant.

Prerequisites

• Your apps already use the same Logto tenant for sign-in.
• An M2M application in Logto admin with the Logto Management API resource and the relevant scopes (update:users, read:roles, manage:organization).

Step-by-step

1. Open the Logto admin console (https://auth.<your-domain>/admin).

2. Roles: create a role like paid-tier, leave permissions to your own discretion.

3. Applications → Create → Machine-to-Machine:

   • Name: OpenBitum glue.
   • API resource: Logto Management API.
   • Scopes: update:users, read:roles, manage:organization.

4. Copy the app ID and secret into .env:

   LOGTO_M2M_APP_ID=ej9...
   LOGTO_M2M_APP_SECRET=KsP...
   

5. Restart the glue.

6. In the dashboard add an entitlement of type Logto role to your product:

   • Role ID: paste the ID of paid-tier.

7. (Optional) Add a Logto organization entitlement to also enrol the buyer into an org for B2B sales.

Using the role in your own app

After purchase, the buyer's next Logto-issued JWT contains roles: ["paid-tier"]. Gate routes on this claim — most Logto SDKs surface it as getRoles().

Troubleshooting

| Symptom | Likely cause | |---|---| | 403 missing scope in glue logs | M2M app is missing update:users | | Buyer's JWT still has no roles | they need to sign out and back in to refresh the token — or your app must call getAccessToken({force: true}) | | 404 not found | wrong role ID — copy from Logto admin URL |

Coming after MVP launch

Auto-revoke on refund, role-bundle entitlements (grant N roles in one shot).