Skip to content
Core Concepts
Projects

Projects

A project is the top-level container in Roled. Think of it as your application’s dedicated space inside Roled. Everything — users, roles, resources, permissions, and clients — lives inside a project.

What Is a Project?

A project represents a single application or service you are building. If you have multiple applications (e.g., an e-commerce admin panel and an analytics dashboard), you can create a separate project for each one.

Each project is completely isolated from others. Resources, roles, and users in one project cannot interact with those in another project; they are completely separate entities.

What a Project Contains

Every project on Roled is a self-contained authorization boundary that includes everything you need to manage authorization for your application. It contains the following components:

ComponentDescription
UsersHuman identities registered in this project
RolesNamed groups of permissions assigned to users
ResourcesEntities you want to protect (e.g., products, orders)
PermissionsActions allowed on resources (e.g., products:create)
ClientsMachine identities (backend services, APIs)

These components are what you will typically design and build, including the project itself, which can be time consuming. However, Roled handles all the heavy lifting for you. You only need to focus on what matters most.

Project Auto-Setup

When you create a new project in Roled, it is automatically provisioned with:

  • Built-in resources: users, roles, resources, permissions, clients
  • Built-in permissions on each of those resources: create, read, update, delete
  • A default client ready to use for OAuth 2.0 flows

This means you can start making authenticated API calls immediately — no additional setup required.

Redirect URIs

A redirect URI is the URL in your application where users are sent after completing the OAuth 2.0 Authorization Code Flow.

A redirect URI is required when you want to leverage Roled’s Fully Managed Users model. This allows you to use Roled’s built-in authentication system. You must register at least one redirect URI in your project before users can authenticate. Otherwise, it is optional.

Example:

https://example.com/auth/callback

You can also set a login URL per redirect URI, which is an initial URL in your application where users are sent to Roled’s /authorize page for authentication. This URL will be used to reinitiate the authentication flow in some cases, such as after a password reset or an email verification process.

API Usage Example

Get a project details:

curl --request GET \
  --url https://auth.roled.id/api/v1/projects/2JUSLUee46xG6iEwG8JwPc \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJo...'

Response:

{
  "success": true,
  "data": {
    "id": "2JUSLUee46xG6iEwG8JwPc",
    "created_at": "2026-07-15T10:00:00Z",
    "updated_at": "2026-07-29T08:30:00Z",
    "name": "Business App",
    "description": "App for managing business operations",
    "logo_url": "https://example.com/logo.png",
    "redirect_uris": [
      {
        "redirect_uri": "http://localhost:4000/auth/callback",
        "login_url": "http://localhost:4000/login"
      },
      {
        "redirect_uri": "https://example.com/auth/callback",
        "login_url": "https://example.com/login"
      }
    ],
    "is_active": true
  }
}

Key Points

  • A project is a self-contained authorization boundary — changes in one project never affect another.
  • Each project gets sensible defaults so you can start building immediately.
  • Projects map one-to-one with your applications — one application, one project.
  • The project id is used as the audience (aud) claim in every JWT issued for that project.
Core ConceptsUsers