> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://mediakind.ferndocs.com/platform/how-to/management/org-provisioning/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mediakind.ferndocs.com/_mcp/server.

# Provision org and users

This guide covers the setup that happens first in a new MK.IO environment: confirm the organization, create a project, assign billing, then prepare access for the people and automation that will use it. Each resource here has its own detailed guide; this page is the order to do them in.

A project is the container that holds your media objects, and each project and payment method belongs to exactly one organization. So the sequence is always organization, then billing, then project, then access.

## Step 1: Confirm or create the organization

Check which organization the current token belongs to:

* Terminal window

```bash
curl -X GET "https://app.mk.io/api/v1/organization" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

```

If the user needs a new organization, create one. Only `name` is required; the legal-entity fields are optional.

```bash
curl -X POST "https://app.mk.io/api/v1/organization" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "name": "Example Media Organization",
      "legalEntityName": "Example Media Ltd",
      "legalEntityContactEmail": "legal@example.com"
    }
  }'

```

## Step 2: Pick a payment method

A project cannot be created without a payment method, so list the ones available first:

```bash
curl -X GET "https://app.mk.io/api/v1/organization/paymentMethods" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

```

If the chosen method requires terms acceptance, accept them before assigning it:

```bash
curl -X POST "https://app.mk.io/api/v1/organization/paymentMethods/<PAYMENT_METHOD_ID>/acceptTermsAndConditions" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

```

## Step 3: Create the project

A project is created with `PUT`, using the name in the URL. It requires `displayName`, `locationName`, and `paymentMethodId`.

```bash
curl -X PUT "https://app.mk.io/api/v1/projects/production-media" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Production Media",
    "locationName": "westeurope",
    "paymentMethodId": "<PAYMENT_METHOD_ID>"
  }'

```

Assigning a payment method also activates the project. You can read or replace the assignment later through `/projects/<PROJECT_NAME>/paymentMethod`; see Usage and billing.

## Step 4: Prepare access

Review the users, roles, and scopes the organization already has, which are the inputs for team setup:

```bash
curl -X GET "https://app.mk.io/api/v1/organization/users" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

curl -X GET "https://app.mk.io/api/v1/organization/roles" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

curl -X GET "https://app.mk.io/api/v1/organization/scopes" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

```

Then create a team that grants roles under a scope. See Users and teams for the full access model and the JSON Patch operations used to evolve a team.

```bash
curl -X PUT "https://app.mk.io/api/v1/organization/teams/video-engineering" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "description": "Team for day-to-day project operations",
      "members": {},
      "scopes": {
        "<SCOPE_NAME>": { "roles": ["<ROLE_NAME>"] }
      }
    }
  }'

```

## Step 5: Create automation tokens

Create a token for the systems that will call the APIs. Prefer a `restricted` token for automation so it cannot do more than the job needs. See Tokens.

```bash
curl -X POST "https://app.mk.io/api/v1/user/tokens" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "restricted",
    "description": "Project automation token",
    "organizationId": "<ORG_ID>",
    "permissions": {}
  }'

```

## Step 6: Add webhook rules early

If the project will run jobs or live workflows, add webhook rules at the start rather than waiting until polling becomes painful. That lets your application react to job completion, live channel state changes, and locator creation from day one.

## What goes wrong

Creating a project before billing exists. A project needs a `paymentMethodId`, and some methods need terms accepted first. Do Step 2 before Step 3.

* Assigning everything to individual users. Grant roles to teams under scopes, then add users to teams. It is reusable and far easier to audit.

## What comes next

* Users and teams: roles, scopes, and JSON Patch in detail.

* Tokens: choose token types and inspect token metadata.

* Build with the Media API: move from setup into media workflows.