> ## Documentation Index
> Fetch the complete documentation index at: https://www.oplane.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Applications for API and MCP access

> Create an application in Oplane organisation settings to give CI/CD pipelines, automation, and other tools their own API key with scoped permissions.

An application gives automation, CI/CD pipelines, and other tools access to Oplane's API and MCP server without using a person's login. Each application has its own identity and permissions, and one API key that you can regenerate at any time.

<Info>
  You need the **Org Admin** role to create and manage applications. See [Roles and permissions](/docs/roles).
</Info>

## Create an application

Open the organisation switcher in the top-right corner and click **Org Settings**. Then open the **Application** tab and click **New application**.

<Steps>
  <Step title="Name the application">
    Enter an **Application name** of up to 64 characters. Pick a name that tells your team where the key is used, for example `GitHub Actions - prod deploys`.
  </Step>

  <Step title="Set when the key expires">
    Under **API key expiration**, pick 7, 14, 30, 60, or 90 days, or choose **Custom…** to set a date up to 365 days ahead. The default is 30 days.
  </Step>

  <Step title="Choose workspace access">
    Under **Workspace access**, choose **All workspaces** to include every current and future workspace in the organisation, or **Only selected workspaces** and pick the ones the application can reach.
  </Step>

  <Step title="Set permissions">
    Under **Permissions**, set each area to **No access**, **Read**, or **Read & Write**. See [Permissions](#permissions) below for what each area covers.
  </Step>

  <Step title="Create and copy the key">
    Click **Create application**. Oplane shows the API key once, under the new application in the list. Click **Copy** and store the key in a secret manager, such as your CI provider's secrets.

    <Warning>
      Oplane stores only a hash of the key, so you can't see it again after you leave the page. If you lose it, regenerate the key. Anyone with the key has the access you granted until it expires.
    </Warning>
  </Step>
</Steps>

## Permissions

| Area                        | Covers                                         | Levels                                       |
| --------------------------- | ---------------------------------------------- | -------------------------------------------- |
| Metadata                    | Listing workspaces and members                 | Always **Read**                              |
| Contents                    | Threat models and security requirements        | **No access**, **Read**, or **Read & Write** |
| Organization administration | Organisation settings, workspaces, and members | **No access**, **Read**, or **Read & Write** |

Both **Contents** and **Organization administration** start at **No access**. Grant only what the tool needs. For example, a pipeline that reads requirements needs **Read** on **Contents** and nothing else.

**Organization administration** never lets an application manage other applications or their keys, even at **Read & Write**.

## Use the key

Application keys start with `oak_v1_`. To connect to the Oplane MCP server, send the key as a bearer token in the `Authorization` header:

```json theme={null}
{
  "mcpServers": {
    "Oplane": {
      "url": "https://gravity.oplane.io/mcp/",
      "headers": {
        "Authorization": "Bearer <your-application-key>"
      }
    }
  }
}
```

Keep the key out of files you commit. If your MCP client or CI tool can read values from an environment variable or a secret, use that instead.

For Oplane's REST API, send the key in the `X-API-Key` header.

## Manage applications

The **Application** tab lists every application in the organisation. Each row shows when its key was last used and when it expires, or **This token has expired** once it has. Click the edit icon on a row to open the application. From there you can:

* Change the name, workspace access, or permissions, then click **Update**.
* Click **Regenerate key** to get a new key with a new expiration. The old key stops working right away, so update it wherever it's stored.
* Click **Delete application** to remove the application and revoke its key. Any tool using the key stops working, and you can't undo this.