Skip to main content

Projects and access

This guide provides step-by-step instructions for managing access control, environment settings, service account credentials, secrets, and team members across the Crusoe AI Platform Web Console.

Core access control hierarchy​

Access control in the platform is structured into three clear levels:

  1. Organization (Org): The top-level enterprise boundary. Organizations own projects and user directories. Organization management is reserved for platform administrators.
  2. Project: A secure, isolated workspace. Each project contains its own workloads, vector indexes, databases, secrets, quota limits, and member access list.
  3. Roles & Permissions: Users hold specific roles (member or admin) within a project:
    • Member: Can deploy workloads, execute queries, view logs, and read non-sensitive configurations.
    • Admin: Holds full control, including managing members, revealing secrets, mapping cloud storage, and deleting project resources.

Project Settings and Crusoe Cloud integration​

The Project Settings view links your project workspace to external cloud infrastructure, such as Crusoe Cloud storage buckets and container registries.

Project Settings View

Step-by-step project configuration walkthrough:​

  1. In the left navigation sidebar, navigate to Project → Settings.
  2. Review your project's short ID, display name, and resource quotas.
  3. Under Crusoe Cloud Connection, map your project to Crusoe Cloud storage and container registries:
    • Map to Crusoe Cloud: Supply one Crusoe Cloud key — Access key ID and Secret key. From that key the platform resolves which Crusoe Cloud project this maps to, mints the Managed Inference credential your agents call the model with, and provisions storage and registry repositories in your own account, billed to your own project.
    • Create bucket: Provision dedicated object storage for agent artifacts and models.
    • Create repository: Set up container registry repositories for function and agent container builds.

The object-storage credential the mapping mints​

Mapping the project also mints a real S3 access key from that Crusoe Cloud connection and stores it in your project as the Secret crusoe-object-store (keys aws.accessKey and aws.secretKey). That is the name to give a bucket trigger's credentials Secret, and the console's trigger forms default to it.

A Crusoe Cloud API key is not an S3 key

Do not paste your Crusoe Cloud access key into a bucket trigger. Object storage refuses it with 403 The AWS access key Id you provided does not exist in our records — the same refusal the container registry gives it as a docker password. On screen this looks like a trigger that exists, reads as configured, and never fires. Use crusoe-object-store.

The key is minted only when the project holds no complete credential, so mapping repeatedly does not pile up dead keys. A project connected before this existed gets the Secret when a project admin presses Check again on the Crusoe Cloud connection panel.

Admin Role Required for Settings Updates

Viewing project settings is open to all project members. However, modifying cloud connections or creating storage buckets requires the Project Admin role. Members attempting changes will receive a notice requiring admin elevated permissions.

Service Accounts and machine identities​

Service accounts provide machine identities for automated tools, CI/CD deployment pipelines, and background scripts without using personal user credentials.

Service Accounts View

Step-by-step service account setup:​

  1. Navigate to Security → Service Accounts.
  2. Click Create Service Account.
  3. Enter a descriptive Name (e.g., github-actions-deployer) and assign a project role (member or admin).
  4. Click Create.
  5. Once created, click Generate API Key next to the service account row.
  6. Copy the API key immediately. The secret token is shown once upon creation and cannot be retrieved later.
Key Security

Store generated API keys in a secure secret manager or CI/CD variable store. If an API key is compromised, navigate to Security → Service Accounts, expand the key list, and click Revoke Key to invalidate it immediately.

Secrets Manager​

The Secrets Manager provides encrypted, centralized storage for sensitive configuration data, database passwords, and third-party API keys.

Secrets Manager View

Step-by-step secret management walkthrough:​

1. Creating a project secret​

  1. Navigate to Security → Secrets.
  2. Click Create Secret.
  3. Enter a unique Secret Name (e.g., OPENAI_API_KEY or DATABASE_URL) and paste the sensitive string value.
  4. Click Save Secret.

2. Managing secret versions and workload bindings​

  • Versioning: Updating an existing secret creates a new version while retaining prior historical versions for rollback safety.
  • Audited Reveals: Reveal… is offered only on a secret's own page, never as a per-row button on the list — one secret at a time, behind a confirm, because a reveal button in a row of six is a reveal that happens by accident. It requires the project's admin role (the button is hidden, not disabled, for members) and logs an explicit project.secret.reveal event in the Audit Log.

3. Binding a secret to a workload — bind, then Apply​

Bindings do not live on Security → Secrets. That page carries only a read-only Referenced by list, which answers the one question you need before deleting a secret: is anything still using it? Bind, repoint, unbind and apply are all mounted on the workload's own page.

  1. Open the agent's or function's page and bind the secret to an environment variable name.
  2. Click Apply n pending binding(s).
  3. Confirm the dialog titled Apply bindings to <name>? (its button reads Apply to <name>).
Recording a binding delivers nothing — Apply does

Binding records intent. Until you Apply, the value is not in the workload's Secret and not in its environment, and the console labels such a binding as pending from evidence rather than from a guess.

The consequence bites on the first deploy: a deploy creates the revision before any binding exists, so a handler that reads the variable at import time crashloops with a KeyError on its very first revision. Deploy, bind, then Apply.

Apply is what reads each value — each read recorded in the audit log with your identity — writes it into the workload's Secret, and rolls a new revision so the running workload picks it up. If any one value cannot be read, nothing is written at all: a half-configured workload is worse than an unchanged one. Applying again on an unchanged set re-reads every value, which is how a rotated secret catches up.

Unbinding is deliberately not symmetric: it takes effect immediately. The server deletes the key from the workload's Secret and rolls a revision, and reports both outcomes (revoked, revision_rolled) because either can fail without failing the request. If a revoke fails, rotate the credential — the plaintext is still in the running environment.

Managing projects​

The Administration → Projects view lists all projects you belong to and allows authorized administrators to provision new workspaces.

Creating a new project​

  1. Navigate to Administration → Projects.
  2. Click Create Project.
  3. Provide a Display Name (e.g., Fraud Detection Pipeline) and a unique lowercase Slug (e.g., fraud-detection).
  4. Click Create. The platform automatically assigns a immutable Short ID used in internal routing and workload hostnames.

Renaming vs deleting projects​

  • Renaming a project: Updating a project's display name is completely safe. The underlying short ID never changes, ensuring zero disruption to live agent endpoints or database connections.
  • Deleting a project: Deleting a project is permanent and irreversible.
Crucial Project Deletion Warning

Deleting a project is refused — HTTP 409 — while it still holds anything of any kind, and the error names what is left, for example:

project fraud-detection still holds 2 agents, 1 memorystore, 3 running workloads. Delete them first, or repeat this call with ?cascade=true to delete the project AND everything in it (this destroys their code, data and logs).

Every kind is counted, not just agents: agents, MCP servers, published services, memorystores, topics, subscriptions, triggers, vector indexes, and running workloads.

?cascade=true is the explicit override. It destroys the project and everything in it — code, data and logs — with no recovery. In the console this is a second, separate confirmation: the first dialog is "delete this project", and when the API answers 409 the console shows you its list verbatim in a new dialog headed Delete everything in <project>? with the button Delete project and contents. Backing out of that second dialog leaves the project intact.

The default project cannot be deleted at all — the API answers 403 — because every pre-projects agent belongs to it.

Member management and IAM​

The Project → IAM & members page controls access permissions for team members and service accounts.

Step-by-step member workflow:​

1. Adding an existing user account​

  1. Navigate to Project → IAM & members.
  2. Click Add Member.
  3. Enter the email address of an existing platform account.
  4. Select the desired role (Member or Admin).
  5. Click Grant Access.

If a user does not have an existing platform account, invite them via a secure invitation link:

  1. On the IAM page, click Invite.

  2. Enter the user's email address and assign their role.

  3. Click Generate Invitation.

  4. Copy the invitation link exactly as the console prints it. Send it to the invitee via your organization's communication channel (email, Slack, Teams). The platform does not send automated emails.

    https://console.codyhill.dev/#/invite/kJ3xQ8pVv2Nf7LcTz0RaYw1BdHmE6sUiXoQ4gZn9tKM

    The token is 32 random bytes in base64url — no inv_ prefix — and the acceptance page is registered on the #/invite/<token> fragment route, the only page in the console that renders without a session. Copy the whole string rather than assembling or truncating one: the fragment is not sent to the server, so a mangled link fails at the browser with no server-side trace.

  5. Acceptance: When the invitee opens the link, they will be prompted to choose a permanent password (minimum 12 characters) and automatically join the project workspace.

One-Time Invitation Link

The token is displayed only once when generated, and accepting consumes it. If the recipient loses the link — or a chat client mangles it — click Revoke on the open invitation row and generate a new one; there is no way to re-read the original.

3. Changing roles or removing members​

  • To promote or demote a user, locate their row in the IAM table, click the role dropdown, and select the new role.
  • To revoke access, click Remove.
Last-Admin Protection Guard

To prevent accidental project lockout, the platform blocks demoting or removing the final remaining Project Admin with the guard error: this is the project's only admin - promote someone else first Promote another team member to Project Admin before modifying the original admin's permissions.

Organizations and user directory (platform admins)​

Platform administrators manage global organization settings under Administration → Organizations:

  • Provision Organizations: Create distinct enterprise organization tenants.
  • User Directory: Provision new user accounts, assign temporary sign-in passwords, or reset credentials.
  • Platform Roles: Toggle global roles between user and admin.
  • Org Admin Inheritance: Granting a user the Organization Admin role automatically inherits admin permissions across all projects within that organization.

Access management action summary​

ActionRequired RoleSafety Guards & Checks
Create ProjectOrg Admin / Platform AdminUnique slug validation
Rename ProjectProject AdminSafe operation; short ID remains unchanged
Delete ProjectProject Admin409 while it holds anything of any kind; ?cascade=true and a second confirmation destroy everything; the default project cannot be deleted
Map Cloud RegistryProject AdminRequires Crusoe Cloud admin permissions
Manage SecretsProject Admin (reveal, delete); any member (create, rotate, bind)Plaintext reveals strictly audited in log; a binding delivers nothing until Apply
Create Service AccountProject AdminAPI keys generated once upon creation
Add / Remove MemberProject AdminProtected by Last-Admin guard
Generate Invite LinkProject AdminLink shown once; non-retrievable

Next steps​