Bring your own user management

​

Introduction

​

Choose the right approach

• Motto’s native user system — Motto handles sign-up, sign-in and tokens for you. This is the default option.
• Motto’s built-in OIDC integration — If your identity provider supports OpenID Connect, connect it in the Motto Studio under OTT → Integrations → OpenID Connect. Motto runs the sign-in with your identity provider, your end-users keep their existing credentials, and Motto issues the tokens.
• OIDC ID token exchange — If your apps already run their own OpenID Connect sign-in, they exchange the ID token your identity provider issued for a Motto token. No server-side code is needed. This guide explains how.
• Tokens created on your server — If your user management system does not support OpenID Connect, for example a proprietary customer database or a legacy membership platform, your server creates the tokens through the Studio API. See Advanced: create tokens on your server.

​

Exchange an OIDC ID token

​

How it works

1. The end-user signs in on your app through your identity provider, which returns an ID token to the app.
2. Your app sends the ID token to the Content Delivery API.
3. Motto verifies the ID token against your OIDC integration: its signature against your identity provider’s published keys, its issuer, its audience and its expiry.
4. Motto returns a Motto token and a refresh token to your app.
5. Your app sends the Motto token in the X-Motto-Token header on every request to the Content Delivery API.

​

Prerequisites

• An identity provider that supports OpenID Connect and signs its ID tokens with an asymmetric algorithm, such as RS256 or ES256
• Your identity provider’s issuer URL, the URL at which it publishes its OpenID Connect discovery document
• The client IDs that your apps use at your identity provider
• Your project’s public key, the same one your app already sends to the Content Delivery API. In the Motto Studio, click your user profile in the top-right corner, then go to API Keys → Project public key.

​

Get Started

1. Navigate to OTT → Integrations → OpenID Connect.
2. Fill in the fields the exchange needs, unless your integration already has them:
   • Provider Name — A name for your identity provider, for your own reference.
   • Issuer URL — Your identity provider’s issuer URL. Motto reads your identity provider’s signing keys from it, and only accepts ID tokens issued by it.
   • Client ID — The client ID of one of your apps at your identity provider. Motto accepts ID tokens issued to this client.
3. Open the Advanced section and scroll down to ID Token Exchange.
4. Turn on Allow ID Token Exchange.
5. Under Additional Client IDs, enter the client IDs of your other apps at your identity provider, separated by commas. You can skip this if all your apps use the client ID from step 2.
6. Click Publish.

curl -X POST "https://cda.mottostreaming.com/motto.cda.iam.auth.v1.AuthService/ExchangeOIDCIDToken" \
  -H "Authorization: Bearer <your_public_key>" \
  -H "Content-Type: application/json" \
  -d '{ "idToken": "<id_token>" }'

{
  "token": "<motto_token>",
  "refreshToken": "<refresh_token>"
}

​

Keep the end-user signed in

curl -X POST "https://cda.mottostreaming.com/motto.cda.iam.auth.v1.AuthService/RefreshToken" \
  -H "Authorization: Bearer <your_public_key>" \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "<refresh_token>" }'

​

Advanced: create tokens on your server

curl -X POST "https://api.mottostreaming.com/iam/users/v1/<user_id>/token?project_id=<your_project_id>&role=ROLE_DEFAULT&ttl=86400s" \
  -H "Authorization: Bearer <your_api_token>"

{
  "token": "<motto_token>",
  "refresh_token": "<refresh_token>"
}

// app/api/motto-token/route.ts
import { NextResponse } from 'next/server';
import { getSession } from '@/lib/auth'; // your own user management system

export async function POST() {
  const session = await getSession();
  if (!session) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const url = new URL(
    `https://api.mottostreaming.com/iam/users/v1/${encodeURIComponent(session.userId)}/token`,
  );
  url.searchParams.set('project_id', process.env.MOTTO_PROJECT_ID!);
  url.searchParams.set('role', 'ROLE_DEFAULT');
  url.searchParams.set('ttl', '86400s');

  const res = await fetch(url, {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.MOTTO_API_TOKEN}` },
  });
  if (!res.ok) {
    return NextResponse.json({ error: 'Token exchange failed' }, { status: 502 });
  }

  const { token } = await res.json();
  return NextResponse.json({ token });
}

X-Motto-Token: <motto_token>

​

Next Steps

• Create User Token
• Users in Motto
• Studio API authentication