Nodium Screenshot API -- Organizations & Roles

Manage team workspaces, invite members, and control access with role-based permissions.

Table of Contents

• Organization Concept
• Roles
• Permissions Table
• Inviting Team Members
• API Key Scoping
• Transferring Ownership
• Managing Multiple Organizations
• SSO Integration

Organization Concept

An organization is a shared workspace that provides a shared credit pool, centralized billing, shared API keys with scoped permissions, a unified usage dashboard, and consistent configuration for notifications, webhooks, and storage integrations. Every API key, credit allowance, and setting belongs to an organization. When you create an account, a personal organization is automatically created for you.

Each organization has a unique identifier (e.g., org_abc123) and a display name that you can customize in the dashboard.

Roles

Every member of an organization is assigned one of four roles:

Permissions Table

Note: Admins cannot remove or change the role of the Owner. Only the Owner can promote another member to Owner (which simultaneously transfers ownership).

Inviting Team Members

Via the dashboard

1. Go to Settings > Organization > Members.
2. Click Invite Member.
3. Enter the email address and select a role.
4. Click Send Invitation.

The invited person receives an email with a link to accept the invitation. If they do not have a Nodium account, they can create one during the acceptance flow.

Via the API

curl -X POST "https://api.nodium.io/api/v1/screenshot/organization/members" \
  -H "X-Access-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "colleague@example.com",
    "role": "member"
  }'

Response:

{
  "invitation_id": "inv_xyz789",
  "email": "colleague@example.com",
  "role": "member",
  "status": "pending",
  "expires_at": "2026-03-12T14:30:00Z"
}

Invitations expire after 7 days. You can resend or revoke pending invitations from the dashboard or API.

Listing members

curl "https://api.nodium.io/api/v1/screenshot/organization/members" \
  -H "X-Access-Key: YOUR_API_KEY"

Response:

{
  "members": [
    { "user_id": "usr_001", "email": "owner@example.com", "role": "owner", "joined_at": "2025-11-01T10:00:00Z" },
    { "user_id": "usr_002", "email": "admin@example.com", "role": "admin", "joined_at": "2025-12-15T09:00:00Z" },
    { "user_id": "usr_003", "email": "dev@example.com", "role": "member", "joined_at": "2026-01-10T14:00:00Z" }
  ],
  "pending_invitations": [
    { "invitation_id": "inv_xyz789", "email": "colleague@example.com", "role": "member", "status": "pending", "expires_at": "2026-03-12T14:30:00Z" }
  ]
}

API Key Scoping

API keys are created within an organization and can be scoped to limit their capabilities:

Creating a scoped key

curl -X POST "https://api.nodium.io/api/v1/screenshot/organization/api-keys" \
  -H "X-Access-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Screenshots",
    "scopes": ["screenshot"],
    "expires_at": "2027-03-01T00:00:00Z"
  }'

Response:

{
  "key_id": "key_abc123",
  "access_key": "nod_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "Production Screenshots",
  "scopes": ["screenshot"],
  "created_by": "usr_001",
  "expires_at": "2027-03-01T00:00:00Z"
}

Security recommendation: Create separate API keys for different environments (production, staging, development) and limit each key to the minimum required scopes. Rotate keys periodically and revoke any that are no longer in use.

Transferring Ownership

Only the current Owner can transfer ownership to another member of the organization.

1. Go to Settings > Organization > Transfer Ownership.
2. Select the member to promote to Owner.
3. Confirm the transfer.

After the transfer:

• The selected member becomes the new Owner.
• The previous Owner is automatically demoted to Admin.
• Billing responsibility transfers to the new Owner.
• All existing API keys and settings remain unchanged.

Important: Ownership transfer is immediate and cannot be undone without the new Owner's cooperation. Ensure you select the correct member.

Managing Multiple Organizations

A single Nodium account can belong to multiple organizations. This is useful for agencies, freelancers, or developers who work across different teams or clients.

Switching organizations

• Dashboard: Use the organization selector in the top navigation bar.
• API: Include the X-Nodium-Org header with the organization ID:

curl "https://api.nodium.io/api/v1/screenshot/usage" \
  -H "X-Access-Key: YOUR_API_KEY" \
  -H "X-Nodium-Org: org_abc123"

If omitted, the API uses the default organization associated with the API key.

Creating a new organization

curl -X POST "https://api.nodium.io/api/v1/screenshot/organization" \
  -H "X-Access-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client Project X"
  }'

Each organization has its own plan, credit allowance, and billing. You become the Owner of any organization you create.

SSO Integration

Single Sign-On is available on the Enterprise plan. Nodium supports the following identity providers via SAML 2.0:

Setting up SSO

1. Contact sales@nodium.io to enable SSO on your Enterprise organization.
2. Provide your Identity Provider metadata URL or XML.
3. Nodium configures the SAML integration and provides the Service Provider metadata.
4. Configure attribute mapping (email, first name, last name, role).
5. Test the integration with a login flow.

Once configured, you can enforce SSO so that all members must authenticate through your identity provider (password login is disabled). Enable just-in-time provisioning to automatically add first-time SSO users to the organization with a default role (Member or Viewer).

Next Steps

• Credits -- Understand credit costs and plan allowances
• Notifications -- Configure alerts for team activity
• Getting Started -- Capture your first screenshot
• API Reference -- Complete endpoint and parameter reference