Getting Started

O2ID is the identity platform that shapes itself to your product, not the other way around. It handles the parts every application eventually needs: sign-in, session management, OAuth 2.0 and OpenID Connect, users, applications, agents, and resource access, as a single, programmable system. The rest of this guide walks you through standing up a server and making your first authenticated request, start to finish, in a few minutes.

Installation

Install the latest O2ID release for your platform (Linux and macOS, amd64 and arm64) with:

curl -fsSL https://o2identity.pages.dev/install.sh | sh

This installs:

• the o2id server distribution, downloaded as an o2id-<os>-<arch>.zip bundling the o2id binary, a default o2id.toml, and a run.sh launcher, and unzipped into its own directory under the current directory
• o2idctl, the management CLI, installed onto your PATH (/usr/local/bin by default; set O2IDCTL_INSTALL_DIR to install elsewhere)

Alternatively, run O2ID as a Docker container instead.

note

To install just o2idctl (skipping the server), run:

curl -fsSL https://o2identity.pages.dev/install.sh | sh -s o2idctl

Start the server

Run the following from the directory where you extracted the release archive:

./run.sh

The server starts on port 8080 by default. pass along -addr server flag to run on a different port, e.g. ./run.sh --addr :9090.

Setting up the platform admin

The very first time O2ID runs against an empty database, it prompts for a username and password for the platform admin user, and assigns them a seeded Platform Admin role with all administration permissions.

No users found — set up the platform admin account.

Username: admin@example.com
Password:

Created platform admin admin@example.com

See Managing Roles for how to create more limited roles, and the API Reference for what each scope grants.

Verify the service is running

Verify that the service is running by invoking the /health endpoint:

curl http://localhost:8080/health

You should see the following response:

{"status":"ok"}

Connect the CLI

Installed in the installation section, o2idctl is O2ID's standalone management CLI; it invokes a running O2ID server's HTTP API to manage its resources.

Quick start

Run the following command to go through connecting to your first O2ID instance in one guided flow.

o2idctl init

it prompts for an API base URL and a profile name, saves the config profile and activates that profile for the current terminal session, then offers to log you in right away.

note

o2idctl can save more than one profile, for interacting with multiple O2ID deployments, or with multiple tenants on the same one — every tenant needs its own separate login, so switching tenants means switching profiles. See the config commands in the CLI Reference for more details.