Rollup ID is a cutting-edge user management platform, meticulously crafted to prioritize privacy, security, and user-friendliness. Our primary goal is to empower users by providing a digital identity solution that places them at the center, allowing them to take control of their online data and identities.

At the same time, we understand the needs of applications. That's why Rollup ID is designed to offer enhanced security, control, and lifecycle management for your application. With Rollup ID, you can ensure a secure and seamless user experience while maintaining the highest standards of data privacy and protection.

Join us on this journey towards a more secure and privacy-focused digital world. Welcome to Rollup ID.

Get Started

Learn More

Rollup ID is an innovative Identity Provider (IDP) that leverages a unique, decentralized approach to identity management. By adhering to established protocols such as OAuth 2.0 and OpenID Connect (OIDC), Rollup ID offers a secure, consent-based authorization mechanism, enabling users to interact safely with online applications. This article will explore OIDC and its application within the Rollup ID platform.

Understanding OIDC

OpenID Connect (OIDC) is a straightforward identity layer built on top of the OAuth 2.0 protocol. It enables clients to verify an end-user's identity based on the authentication performed by an authorization server. Additionally, OIDC provides basic profile information about the end-user in an interoperable and REST-like manner.

OIDC plays a crucial role in standardizing user authentication, simplifying the process for various online services to share this responsibility securely.

The Application of OIDC in Rollup ID

Rollup ID not only embraces the OIDC and OAuth 2.0 standards but also introduces a layer of decentralized control. This approach effectively returns the control of privacy and data security to the users. Here's how it works:

• Decentralized Control: Unlike traditional OIDC setups where authorization tokens are issued by the IDP, in the Rollup ID ecosystem, users issue these tokens themselves. This user-centric approach provides full control and transparency to the users over their authorizations.

• Consent-based Authorizations: Rollup ID operates on consent-based authorizations to services and data, giving users complete control over which applications can access their data and the extent of this access.

• Flexible and Extensible Claims: Authorization claims can include access to profile data, linked accounts, email addresses, Personally Identifiable Information (PII) / Know Your Customer (KYC) data, smart contract wallets, and more. The platform is also designed to allow third-parties to publish custom claims in the future.

By incorporating these features, Rollup ID achieves "logical" or "sufficient" decentralization. It provides a secure, private, and user-controlled identity platform that adheres to the standards set by OIDC, ensuring a seamless and secure online experience for all users.

Registering Applications with Rollup ID

Before OIDC authentication can take place, developers must register their applications with Rollup ID. This can be done by create a new application on the and following the .

Authentication Flow

Rollup ID supports the authorization code from the OIDC spec. Although applications without backend servers (that may be running purely client-side) are more suited to implicit authentication flows, they are no longer recommended as they are not secure.

Authentication begins with a request to the /authorize endpoint. When using the native Sign In with Rollup ID page, most of the OIDC process is handled for you. You can begin the authentication cycle by redirecting your users to the /authorize endpoint with the appropriate parameters.

Redirect Responses

Once successfully authorized, the user is redirected back to your application. The redirect URL will contain a number of values, depending on the flow you are using.

The authorization code flow, the redirect URL will contain the code (an authorization code that can be exchanged for an ID token) and the state (the optional state value passed to the /authorize endpoint).

ID Token Verification

ID tokens must always be verified and should not be blindly accepted. To verify an ID token, fetch the public key from the endpoint. More details about this process can be found in the API documentation.

This guide will walk you through how to request email addresses from your user using the Email Scope.

Step 1

In your application OAuth configuration make sure that the "email" scope is selected in the "allowed scopes" dropdown. Make sure to save this configuration before moving to step 2.

Step 2

When make sure you add email to the scope query param. Your auth url should look something like this https://<rollup.id or your custom domain>/authorize?client_id=xxx&state=xxx&scope=email

Step 3

After authenticating into your custom Rollup application, your users will we be presented with an authorization screen containing the email scope authorization request.

If the user already as a connected email, this email will be automatically selected. If no email address is connected to their identity they can connect an new email address and continue.

Step 4

When redirected back to your application, the will now contain an authorization for email address. The email address will also be available returned in the user token via the .

The dashboard is where you will be presented with an overview of your application keys, connected smart contracts, and user sessions.

Here you can also copy and rotate your Galaxy API key for authenticating into the .

TODO

Step 1: Connect with Rollup Passport

• Begin by visiting the Rollup Console and logging in.

• Once logged in, you'll land on the dashboard. If this is your first time logging in you will be presented with an quick onboarding flow where you will be directed to create an application.

Step 2: Register Your Application

• In your personal or group dashboard click on the "Create Application" button.

• Provide a name for your application. After this, you'll be redirected to the application's configuration screen.

Step 3: Configure your Application

On the application dashboard, you can obtain your Galaxy API key and application keys.

Navigate to the "OAuth" section for a comprehensive application configuration. Here, you'll find a standard configuration form. Ensure you fill in the required fields to customize your auth flow:

• Application Name: The name of your application. This will be displayed to users during the auth flow.

• Redirect URL: Where Rollup redirects users post-authentication to exchange tokens (more details on this on next page).

• App Icon: Your application's logo, which will be displayed to users during the auth flow.

Once all details are filled in, activate the "Published" toggle and hit the "Save" button. With your application fully configured, you're now ready to complete integrate the auth flow into your app.

Onboard users to blockchain

Ethereum account abstraction and user deposit vault accounts provide secure and flexible management of funds on the Ethereum blockchain. With this feature, apps can sponsor gas fees can interact with a smart contract wallet using the Galaxy API, while each user's funds are kept in a separate deposit vault account, reducing the risk of unauthorized access or loss of funds.

After completing the and obtaining a user's ID token and access token, you can choose from several strategies to connect users to your app's database. For more information on the ID token, refer to the documentation.

ID Token

You can create a user in your database using the ID token. The ID token contains the user's unique identifier in the subject (sub) field, which can serve as a reference for the user in your database. The ID token also includes the user's profile information, allowing you to populate user details in your database accordingly.

You can configure Rollup ID as a generic OAuth2 authorization server by following .

Manage Permissions

The team management, roles, and permissions feature allows yo to control access and enhance security by defining roles and permissions for team members.

Fast KYC

The KYC feature enables fast and secure user onboarding by streamlining the identity verification process. It helps businesses comply with regulations related to fraud prevention and anti-money laundering, ensuring a safer environment for both the organization and its customers. KYC is an essential feature for businesses looking to onboard users quickly and efficiently while maintaining compliance with regulations.

TODO

Direct User Acquisition

With the zero-knowledge audience builder tool, businesses can identify and target specific groups of potential users, creating personalized marketing messages that optimize user acquisition efforts. This feature enables businesses to launch their application and acquire their first and next users efficiently and effectively, ensuring a successful launch.

Customize your Login Experience

With a white label feature in your authentication tool, you can customize the user interface to match your brand, giving a seamless experience to your users. This not only enhances brand consistency but also establishes trust with users, making it an essential security measure for protecting sensitive data.

Where do I get support?

You can get support from the team by joining our Discord or documenting any issues at our Github.

When will WebAuthn/Passkeys be supported?

Passkeys/WebAuthn has now been implemented and is now one of the available authentication methods in Rollup Passport.

What is a Vault and when will it be available?

Vault is an ETH "burner wallet" linked to a user identity and can be created by developers using progressive authorizations. Access to these wallets is governed by advanced OAuth scopes and available over API and is perfect for onboarding non-technical users to blockchain powered applications.

You can check out progress on this feature .

How do I claim my promotional credits?

1. Login to

2. Go to the "Billing and Invoicing" section on the bottom left navigation.

3. Follow the prompt to select a billing email address.

4. Email with the email address selected in step 3. If you are claiming the additional $200 existing app credit and $200 1000 MAU credit let us know in the email by providing your app domain name and a screenshot of your total users.

This guide will walk you through how to request email addresses from your user using the Connected Accounts Scope.

Step 1

In your application OAuth configuration make sure that the "connected accounts" scope is selected in the "allowed scopes" dropdown. Make sure to save this configuration before moving to step 2.

Step 2

When make sure you add connected_accounts to the scope query param. Your auth url should look something like this https://<rollup.id or your custom domain>/authorize?client_id=xxx&state=xxx&scope=connected_accounts

Step 3

After authenticating into your custom Rollup application, your users will we be presented with an authorization screen containing the connected accounts scope authorization request.

By default "All Connected Accounts" will be selected. Users will have the option to filter down connected accounts.

Step 4

When redirected back to your application, the will now contain an authorization for connected accounts. The connected accounts will also be available returned in the user token via the .

Overview

Galaxy API is a versatile interface that enables developers to traverse the Rollup ID graph using their application API keys paired with user-issued access tokens. It provides both GraphQL and REST endpoints, allowing developers to choose the best approach to interact with the decentralized profile graph and perform various operations.

Key Features

• GraphQL API: The Galaxy GraphQL API allows developers to make flexible and efficient queries, enabling them to request precisely the data they need, reducing the amount of over- or under-fetching.

• REST API (coming soon): The Galaxy REST API offers developers a more familiar and straightforward way to interact with the Rollup ID graph using standard HTTP methods.

• Authorization: Developers must use their application API keys paired with user-issued access tokens to access the Galaxy API, ensuring secure and authorized access to the graph.

Using the Galaxy API

Authentication

To authenticate with the Galaxy API, developers must use their application API keys and user-issued access tokens. These tokens ensure that only authorized applications can access the graph, and only with the specific permissions granted by the user.

Making Requests

Developers can make requests to the Galaxy API using either the GraphQL or REST endpoints:

1. GraphQL Requests: Developers can send GraphQL queries and mutations to the GraphQL endpoint, allowing them to fetch or modify data efficiently.

2. REST Requests: Developers can use standard HTTP methods (GET, POST, PUT, DELETE) to interact with the REST API endpoints, providing a more familiar approach to working with the Rollup ID graph.

Traversing the Graph

Using the Galaxy API, developers can traverse the Rollup ID graph by making requests to access and interact with nodes and edges. These interactions are subject to the access tokens issued by the user, ensuring that developers can only access the specific data and relationships permitted by the user.

To traverse the graph, developers can use the Uniform Resource Name (URN) format from to resolve nodes on the graph. For example, urn:rollup:account/abc123 tells us that within the "rollup" domain, get the "profile" node with the namespace id "abc123".

The OAuth tab is where you can configure your applications standard OAuth settings including the name and logo that will appear in the flow for your users.

This is the most important configuration in this tab is the . Every scope represents an authorization request that will be presented to the user during the auth flow in Passport. These authorizations include access to profile information, connected accounts, provisioning wallets and more.

Settings Panel

For this guide we will be setting up an OAuth provider as by NextAuth.js.

Step 1

Follow the getting started guide for initial setup instructions.

Two types of tokens are related to user authentication and authorization: ID tokens and access tokens.

ID tokens

ID tokens are JSON web tokens (JWTs) intended for use by the application only. By default, all Rollup apps send a minimal ID token in the callback following the authentication flow. Your app should parse the token's contents and use the information (including details like name and profile picture) to customize the user experience.

The decoded contents of an ID token looks like the following:

ID tokens can be treated as authentication tokens for your application. You can store this token with the user's profile in your database using the subject as the unique user identifier and use it to personalize the user's experience. However, sending an ID token to the Galaxy API will not work.

Access tokens

Access tokens are JWTs used to inform the Galaxy API that the bearer of the token has been authorized to access the API and perform a predetermined set of actions (specified by the granted scopes). An app can request scopes through the Console OAuth settings page, and the user can grant or deny access to the scopes during the authentication flow.

Access tokens must never be used for authentication. They do not confirm if the user has authenticated. Access tokens only possess the user ID, located in the sub claim. Treat access tokens as opaque strings since they are meant for APIs. Your application should not attempt to decode them or expect to receive tokens in a particular format.

Here is an example of an access token:

Access tokens do not contain any user information other than their ID (sub claim) and authorization information about the actions the application is allowed to perform via the API (scope claim). This makes them useful for securing an API but not for authenticating a user.

In some situations, it may be desirable to include additional information about the user or other custom claims in the access token to save the API from having to fetch details about the user. If you choose to do this, be aware that these extra claims will be readable in the access token. Non-access claims, however, will be readable in the ID token. To learn more, read .

Refresh Tokens

In addition to ID tokens and access tokens, OAuth 2.0 also introduces the concept of refresh tokens. A refresh token is a special kind of token that can be used to obtain a renewed access token. This is useful in situations where the access token has expired or has been invalidated, and the application needs to gain access to the user's resources without having to re-authenticate the user.

Refresh tokens are typically long-lived and can be used to request new access tokens from the authorization server. This is done by sending a request to the token endpoint of the authorization server, including the refresh token along with the client's ID and secret.

Here is an example of a refresh token:

In the Pro version of Rollup, you can set the issuer (iss) to your own custom domain. See the custom domain feature in your Console app.

Refresh tokens provide a more seamless user experience by reducing the need for the user to re-authenticate and grant permissions, while also maintaining the security and privacy of the user's data. However, because refresh tokens can be used to obtain new access tokens, they must be stored securely and treated with the same level of care as the user's credentials.

To learn more about using refresh tokens with Rollup ID, refer to our and resources.

This is a listing of scope values Rollup supports and plans to support for Rollup accounts.

Scopes

Overview

As of April 2023, Supabase does not support the OIDC standard as a form of authentication. As a workaround, Rollup repurposes their Keycloak plugin to achieve the same effect.

This involves multiple redirects:

In order to implement these hops, configure Rollup, Supabase, and your app as follows:

Console Configuration

Request authorization for the Email scope and set the Redirect URL to the Supabase Keycloak provider's redirect URL. You can get the redirect URL from the Keycloak provider configuration (see below).

Required scope values are:

• Email

• Profile

OpenID is an optional scope suggested for standards-compliant OIDC connections.

Save and publish your application.

Supabase Configuration

Within Supabase, select "Authentication" a nd then under "Configuration" select "Providers" and under the "Email" settings disable "Confirm Email" and save.

Next go to the Keycloak settings and enable Keycloak.

Update your Keycloak configuration's Client ID and secret with the values from your Rollup Console Application.

Set your Keycloak Realm to https://passport.rollup.id (the screenshot below shows our development environment).

Copy your callback URL here and use it in your Rollup Console Application configuration (see above).

Save your settings.

App Configuration

Within your application, use the Supabase library to sign the user in with the configured Keycloak provider:

After completing the auth flow and obtaining a user's ID token, you can apply various strategies to manage authenticated users within your app.

For more information on the ID token, refer to the Tokens documentation.

Browser Applications

Session Cookies

The most common method to authenticate a user's session in a browser application is by using session cookies. A session cookie can store simple user information, such as the ID token received through the authentication flow or a basic user ID. You can use this session cookie to validate the user's session for every subsequent server request.

As a developer, you can set and reset expiry times on the session cookie to control the duration of the user's login. Most web frameworks have built-in support for session cookies.

TODO: example code

Session Storage

For single-page applications (SPAs) without a backend, you can use browser session storage to store tokens.

TODO: example code

Native Applications

The most common way to authenticate users in a native application is by using on-device secure storage to store tokens and maintain user sessions after the authentication flow. The primary difference with native apps is that you will need to use a WebView or browser to complete the authentication flow. This is achieved by setting the redirect URL to a custom URL scheme you register for your app.

When Rollup redirects to this URL, your app can pick up the exchange code, complete the authentication flow, and receive the ID and access tokens.

TODO: example code

Logging Out

To enable users to log out, clear the session cookie or session storage and redirect them to your login page. Your login page should then redirect users to the authentication flow if they are not logged in. The authentication flow will prompt users to continue using their last known identity.

Console is your control centre where you register and manage all your applications. Below is an incomplete tour of the Console app.

Navigation

The navigation consists of two main sections.

At the top right you have your profile menu. Here is where you can sign out and visit your Profile.

On the left is your application context menu. Here is where you can toggle between your applications and also create new ones.

Application List

The very first screen you will see in Console is the list of all your applications in one place. You can also create apps from this screen using the "Create Application" button.

Application Management

Within an application context you will be presented with a few tabs.

Overview

Configuration

CRM

Management

Accessing You User's Smart Contract Wallets

With Rollup your can request access to your users smart contract wallets. If they don't have a smart contract wallet, no sweat, we will help them create one when they onboard to your application. The following will guide you through setting up this flow.

Currently for this feature we only support ethereum and polygon with their testnets. if you'd like to add something else.

TODO

Overview

Rollup ID is designed to act as a "logically" or "sufficiently" decentralized user management platform that allows users to engage with online applications securely and privately. It aims to create simple on-boarding and off-boarding user experiences meeting not only regulatory and compliance requirements but also the needs and expectations of your users.

Core: Open Source Profile Graph

At the core of the Rollup Platform is the open-source Profile Graph, deployed at the edge on Cloudflare's global infrastructure. The Profile Graph was inspired by the . Instead of fully adopting the DID specification, Rollup ID utilizes familiar protocols like OAuth to provide a developer-friendly and user-centric platform that respects the goals of the DID spec:

• Decentralized: End users should be the issuers

• Persistent: Identifiers should be inherently persistent (and deterministic)

• Cryptographically Verifiable: It should be possible to prove control of the identifier

Main Features

• Based on the OAuth 2 and OpenID standards, enabling consent-based authorizations to services and data.

• Authorization tokens are issued by the user, providing full control and transparency into the authorizations.

• Authorization claims can allow access profile data such as, linked accounts, email addresses, PII/KYC data, smart contract wallets, and more.

Edge-Deployed Profile Graph

Rollup ID is an open-source platform deployed at the edge, designed as a decentralized user graph consisting of nodes and edges. The nodes represent different types of objects, such as profiles, accounts, linked addresses, storage, smart contract wallets, applications, and authorizations. The edges represent the relationships between these nodes, enabling traversal and interaction within the graph.

Key Components

• Nodes: Nodes represent different types of objects in the graph, including profiles, accounts, linked addresses, storage, smart contract wallets, applications, and authorizations.

• Edges: Edges represent the relationships between nodes and are used to traverse and interact with the graph.

• Access Tokens: Users issue access tokens through claims and scopes to protect traversal of the graph.

Accessing the Graph

1. Proof of Identity: To log in to Rollup, a user needs to present proof of identity, such as an email address or social account. This proof enables the deterministic discovery of the Address Node on the graph, representing the unique identity factor.

2. Address Node and Account Node: If the Address Node has a linked unique identity (Account Node), the graph can be traversed to this identity. If no identity exsists, one will be created.

3. Authorization Claims: The user's identity can now be asked to issue authorization claims to traverse other edges to nodes on the graph (e.g., profiles, storage namespaces, etc.). Once authorization is accepted, the authorization itself becomes an Access Node, linking the identity on one side to the application that requested the authorization on the other using edges.

User Passports

With Rollup, users have "passports" they can log in to and manage their identities, issued tokens, and other aspects of their Rollup experience. Passports provide users with full control and transparency over their data and authorizations.

You can learn more about Passports .

Exchange Token

Call this method to exchange an exchange code or refresh token for a new access token and refresh token.

Exchange Token

Communicate directly to users

A messaging tool inside a CRM allows businesses to communicate with their users and prospects from a single platform, providing a more efficient and streamlined process. It enables automation, personalized communication, and improved user engagement, resulting in stronger relationships and increased productivity.

The users tab is where you can list and explore users in your application.

Access to Galaxy is served up by a GraphQL (GQL) API at https://galaxy.rollup.id

Setup Guide

There are several ways you can consume GQL APIs and we've documented how below. If you are interested in a deeper understanding of GraphQL you can visit the

Definitions

X-Galaxy-Key Header

This is the API Key that can be found in the dashboard of your App and is required to authenticate into the Galaxy API.

Authorization Header

This is where you provide the JWT received from your user sessions after the .

API Playground

To see the entire API definition you can explore the entire Galaxy API at the .

The Rollup ID authentication flow is built upon the , ensuring a secure and standardized process. This guide will walk you through the steps involved in this flow.

For this step, since Rollup ID is standards-compliant, you can use off-the-shelf to build your OAuth flow.

Configure Custom Domain

A custom domain feature in an authentication tool allows an organization to use its own domain name instead of the tool's default domain. This provides a more seamless user experience, improves brand consistency, and enhances the security of the authentication process by reducing the risk of phishing scams.

Once you've successfully integrated Rollup ID and authenticated your users you can now make authorized requests to the and .

The Galaxy API is both a and API.

When calling the API, you'll need to include the from your app and, in some cases, the signed JWT/access token.

Passport is an OAuth-based authentication and authorization gateway for your app that is hosted and customizable with your domain. It requires minimal integration and can be accessed on any device (desktop, web, mobile) and has the following flow and features.

Auth Flow

Authentication

The authentication step takes care of identifying profiles on the . The authentication method a user chooses acts like a DNS resolver to a users profile. If a profile is not found, one will be created.

Once authenticated the user will be redirected to the authorization screen.

Passport's authentication flow currently supports the following authentication methods and are configurable for your app :

• Connect with Wallet

• Connect with Email

• Connect with Passkeys (aka. WebAuthn)

• Connect with Google

Authorization

The key feature about Rollup's Profile is the authorization step. Based on what you set as your in the OAuth settings, the user will be presented with a branded authorization request to permission and/or provision access to the users identity features on the .

Once authorized the user will be redirected back to your application with the state and exchange code to complete the auth flow and receive an access token.

Tokens & Sessions

The passport application is also responsible for issuing access and refresh tokens via the . It is recommended that these tokens be managed by your application in either a session cookie and/or user record. Tokens can be continuously refreshed so long as the user has not explicitly revoked access.

Authenticated users will also maintain their session with passport for 90 days and that session will be extended long as the user user visits the passport app within the 90 day period. This also means that if your application session expires and the user is redirected to passport you will automatically get another access token and refresh token.