New teams shouldn't have to wait on a CodeScene admin to get started. Using CodeScene's REST API, you can let teams request their own project through a self-service catalog, an internal developer portal, or any workflow tool that can make an HTTP call and have the project created and its requestor assigned as Project Admin automatically, with no manual setup in between.

This guide covers the minimal API calls needed to build that flow: creating a project from just a repository URL, and assigning a specific person as Project Admin on it.

Primary Stakeholders

• Platform / DevOps teams: Build the automation once, expose it through a catalog item, and remove yourselves from the onboarding path.

• Engineering managers: Get new teams set up in CodeScene the moment they ask, without opening a ticket.

• CodeScene admins: Keep governance in place, the automation only does what you allow it to do, and every role assignment still goes through CodeScene's normal role-mapping system.

Prerequisites

• An API token with the right role. Creating a project requires a user with the Admin, Architect, or RestApi role. Assigning roles (the second half of this guide) always requires a user authenticated as an admin, plan for your automation's service account to have Admin access.

• CodeScene must already be able to reach the repository. Adding a repo-paths entry does not grant CodeScene access to a private repository, it only tells CodeScene where to look. Make sure the relevant git host integration (GitHub App, GitLab, Bitbucket, Azure DevOps, or a reachable git credential for on-prem) is already configured. If CodeScene can't clone the repo, the project will be created but analysis will fail.

• Know the identifier CodeScene expects. Role assignment needs an identifier, a username, email, or group name which must match the value CodeScene already has on record for that user or group under the authentication provider you're mapping against (database, OAuth/SSO, or LDAP), not necessarily the value your catalog tool collects. If your catalog captures an SSO email but CodeScene knows that user by a different username, the mapping will silently fail to apply. Check an existing user or group in CodeScene's user management to confirm the exact identifier format before wiring up the automation.

• CodeScene Pro Subscription. Access to the REST-API is only available to customers with a Pro Subscription, not Standard.

Step 1: Create the project

Projects are created with a POST to /api/v2/projects/new. The only required field is repo-paths.

POST /api/v2/projects/new Authorization: Bearer <token> Content-Type: application/json { "config": { "repo-paths": [ "https://github.com/your-org/your-repo.git" ] } }

By default, the project name is derived from the repository name. If you want to set it explicitly, add a name field:

{ "config": { "repo-paths": [ "https://github.com/your-org/your-repo.git" ], "name": "payments-service" } }

Everything else (group assignment, developer configuration, Code Health rules, quality gates) is optional at creation time and can be applied afterwards with a PUT to /api/v2/projects/{project_id} if your onboarding flow needs it. For a minimal onboarding flow, though, the repo URL is genuinely all you need.

The response includes the new project's ID, capture it, since you'll need it for the next step.

Step 2: Assign the requestor as Project Admin

Role assignment is handled through CodeScene's role-mapping endpoints. These exist at three levels: global, group, and project. For onboarding a single new project, the project-level endpoint is the one you want.

One-time setup

Before your automation can assign roles, you need two numeric IDs from your CodeScene instance. Look these up once and store them in your automation's configuration, they don't need to be re-fetched per request.

1. Find your authentication provider ID.

GET /api/v2/authentication-providers

This returns the providers configured on your instance (database, OAuth, LDAP), each with a numeric ID. Use the ID for whichever provider your users authenticate with.

2. Find the role ID you want to assign.

GET /api/v2/roles

This returns the roles available on your instance and their numeric IDs. Both endpoints require admin authentication.

Per-project: assign the role

Once the project exists (Step 1) and you have your provider ID and role ID (one-time setup above), assign the requestor as Project Admin with:

POST /api/v2/projects/{project_id}/role-mappings/{provider_id} Authorization: Bearer <token> Content-Type: application/json { "identifier": "requestor@your-org.com", "role_id": 9 }

identifier is the username, email, or group name exactly as CodeScene knows it for that authentication provider, not necessarily whatever value your catalog tool collected from the requestor. role_id is the Project Admin role ID from your /roles lookup, the value shown here is illustrative; look up the actual ID on your instance, since IDs aren't guaranteed to match across instances or versions.

Equivalent endpoints exist for group-level (/api/v2/groups/{group_id}/role-mappings/{provider_id}) and global-level (/api/v2/authentication-providers/{provider_id}/role-mappings) role mapping, in case your onboarding flow needs to grant broader access instead of a single project.

Putting it together: an example workflow

The two calls above are all a self-service onboarding flow needs. Using a ServiceNow Catalog Item as an example (the same pattern applies to Backstage, Jira Service Management, Port, or any internal developer portal):

1. A user submits a "New CodeScene Project" catalog item, providing a repository URL and, optionally, a project name.

2. The catalog workflow (built in Flow Designer / IntegrationHub, or any orchestration layer capable of making HTTP calls) calls POST /api/v2/projects/new with the repo URL, using a service account token.

3. The workflow reads the new project ID out of the response.

4. The workflow calls POST /api/v2/projects/{project_id}/role-mappings/{provider_id}, passing the catalog requestor's identifier and the pre-looked-up Project Admin role ID.

5. The requestor opens CodeScene and finds their project already there, with themselves already set as Project Admin, no ticket, no manual role assignment.

Limitations and things to note

• Repo access is a separate concern from project creation. The API will happily accept a repo-paths entry it can't reach; make sure your git integrations are in place before you rely on this for onboarding.

• Role-mapping endpoints need admin auth. This is more privileged than the RestApi role used for plain project creation, factor that into how you scope and store the service account token driving the automation.

• IDs are instance-specific. Authentication provider IDs and role IDs are not fixed values, look them up on your own instance rather than hardcoding IDs from examples (including this guide's).

• Creation and role assignment are two separate calls. The project ID doesn't exist until after creation, so the role-mapping call always has to come second.

• A minimal project uses default settings. No group, no custom Code Health rules, no custom quality gates. If your onboarding standard requires any of those, apply them with a follow-up PUT /api/v2/projects/{project_id} call in the same automation.

Frequently Asked Questions

Q: Can we create a CodeScene project with just a repository URL? A: Yes. repo-paths inside config is the only required field for POST /api/v2/projects/new. Everything else is optional.

Q: How is the project named if we don't specify one? A: CodeScene derives the name from the repository. To set it explicitly, add a name field alongside repo-paths in the same request.

Q: Can we automatically make the requestor a Project Admin? A: Yes, via the project-level role-mapping endpoint, POST /api/v2/projects/{project_id}/role-mappings/{provider_id}, once you know the project ID, your authentication provider ID, and the Project Admin role ID.

Q: Do we need to look up the provider ID and role ID every time we onboard a team? A: No, both are static per instance. Look them up once via /api/v2/authentication-providers and /api/v2/roles, and reuse them in your automation.

Q: Does this only work with ServiceNow? A: No. ServiceNow Catalog is used here as an example; the same two API calls work from any tool capable of making sequential HTTP requests. E.g. Backstage, Jira Service Management, a custom internal portal, or a simple script.

Q: What's the biggest prerequisite people miss? A: Repository access. Creating the project via the API doesn't grant CodeScene access to a private repo. Access has to already exist through your configured git integration, or the project will be created but fail to analyse.

Q: Where can I find the full REST API reference? A: The Swagger UI, linked from your CodeScene instance, documents every endpoint, including the ones covered here. See Where to Find the CodeScene REST API Documentation? for direct links for Cloud and On-Prem.

Q: How do I switch from CodeScene Standard to Pro in order to use the REST API? A: Contact sales@codescene.com where we will be happy to help unlock this powerful feature.

Key points to remember

• POST /api/v2/projects/new needs only repo-paths inside config, everything else is optional.

• Add a name field to control the project name; otherwise it's derived from the repo.

• CodeScene must already have access to the repository, the API call doesn't grant that access.

• Look up your authentication provider ID (/api/v2/authentication-providers) and role ID (/api/v2/roles) once, and reuse them.

• Assign the requestor as Project Admin with POST /api/v2/projects/{project_id}/role-mappings/{provider_id}.

• Role-mapping calls require admin authentication, a higher bar than plain project creation.

• The pattern generalises to any self-service catalog or developer portal, not just ServiceNow.