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

# API access for automated workflows

> Set up API credentials for services, scheduled jobs, and other SeekOut MCP workflows that run without a user signing in.

For everyday interactive use — SeekOut MCP inside Claude, ChatGPT, Cursor, or another AI assistant — the standard OAuth sign-in is simpler and recommended, and you don't need machine-to-machine (M2M) credentials. But some environments make browser-based sign-in impractical. In those cases, SeekOut can provision a dedicated M2M credential that gives an automated workflow secure, scoped access to the MCP server.

<Note>
  **If you're used to other vendors' API keys:** SeekOut uses OAuth 2.0 client credentials instead of a static API key. You receive a **client ID** and **client secret** and exchange them for a short-lived bearer token. This is more secure — the secret is rotatable, tokens expire automatically, and access is scoped to the MCP server.
</Note>

## When to use M2M credentials

M2M credentials are intended for non-interactive and automated use cases. Consider them when:

* You're running a **CI/CD pipeline** or scheduled job that calls SeekOut MCP with no human present to complete an OAuth sign-in.
* You're building a **server-side integration** where a backend service — not an individual user — makes MCP requests.
* You're deploying in a **headless or non-interactive environment** where opening a browser for authentication isn't feasible.
* You need a **shared service-account** identity for a team or system process rather than a named user.

## How to get M2M credentials

M2M credentials are provisioned by SeekOut on request — they are not self-service. A SeekOut administrator creates a confidential OAuth client for your organization, configured with the permissions and rate limits your use case needs.

<Steps>
  <Step title="Identify your requirements">
    Be ready to describe what the credential will be used for, what access it needs (for example, search-only vs. workspace write access), and the expected request volume. This lets the team configure the right permissions and rate limits up front.
  </Step>

  <Step title="Contact SeekOut Support or your account team">
    Open a support ticket or reach out to your SeekOut account representative and request **M2M credentials for SeekOut MCP**.
  </Step>

  <Step title="Receive and store your credentials securely">
    SeekOut delivers a **client ID** and a **client secret** (shown once) through a secure channel. Store them in a secrets manager, environment variable, or vault — **never in plain text or source control**.
  </Step>
</Steps>

## How to authenticate

M2M uses the OAuth 2.0 `client_credentials` grant: exchange your client ID and secret for a short-lived bearer token, then send that token on each request to the MCP server.

**1. Exchange your credentials for an access token**

```bash theme={null}
curl -X POST https://app.seekout.io/api/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=mcp:tools" \
  -d "resource=https://seekout-search-mcp.seekout.io/tools"
```

The response contains a short-lived bearer token:

```json theme={null}
{
  "access_token": "<short-lived JWT>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<refresh token>",
  "scope": "mcp:tools"
}
```

**2. Call the MCP server with the token**

```text theme={null}
Authorization: Bearer <access_token>
```

For MCP clients that read a JSON config file, add the token as a custom header:

```json theme={null}
{
  "mcpServers": {
    "seekout-search": {
      "url": "https://seekout-search-mcp.seekout.io/tools",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}
```

**3. Get a fresh access token when it expires**

Access tokens are short-lived (see `expires_in`), so a long-running integration needs a way to renew them. For machine-to-machine access the simplest approach is to **just re-run the step 1 exchange** — your service already holds the client secret, so it can mint a new access token at any time with no extra state to track. A common pattern is to request a token on startup and request another whenever a request returns `401 Unauthorized`.

<Note>
  Don't hardcode a token in a static config file — tokens expire. Fetch one at runtime instead. The client secret itself doesn't expire (though SeekOut can rotate it), which is why re-exchanging it is the recommended path for M2M.
</Note>

**Optional: use the refresh token**

The token response also includes a `refresh_token`, for OAuth client libraries that expect a standard refresh flow. You can trade it for a new access token instead of re-running the full exchange — scope and resource carry over automatically:

```bash theme={null}
curl -X POST https://app.seekout.io/api/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
```

Each refresh returns a **new** `refresh_token` (they rotate on use), so you'd need to persist the latest one. Because it still requires your client ID and secret, it offers little over simply re-running the exchange — for most M2M integrations, step 1 is simpler. Refresh tokens matter most in user-context OAuth flows, where re-authenticating would otherwise require a person to sign in again.

## Security best practices

* **Store secrets in a secrets manager.** Use a dedicated secrets manager (AWS Secrets Manager, HashiCorp Vault, or your CI platform's secret store) rather than committed env files. Inject the secret at runtime.
* **Limit credential scope.** Ask SeekOut to configure the minimum permissions your workflow needs. A credential used only for search doesn't need workspace write access.
* **Rotate credentials after exposure.** If a secret may be exposed — for example, accidentally committed — contact SeekOut Support immediately to rotate it. Don't wait to confirm the exposure.
* **Audit credential usage.** Ask your SeekOut administrator to periodically review credential usage in the admin console. Unused or unexpectedly high-volume credentials should be investigated and rotated.

## OAuth sign-in vs. M2M

|                         | OAuth sign-in (recommended for interactive use) | M2M credentials (for automated workflows)                    |
| ----------------------- | ----------------------------------------------- | ------------------------------------------------------------ |
| **Best for**            | Individual users, AI desktop assistants         | CI pipelines, server integrations, headless environments     |
| **Authentication flow** | Browser-based sign-in via your SeekOut account  | `client_credentials` grant → bearer token in request headers |
| **Credentials**         | Managed by your SeekOut login session           | Client ID + client secret, provisioned by SeekOut            |
| **Rate limits**         | Per-user limits applied to your account         | Configured per-credential by SeekOut at provisioning         |
| **Setup**               | Sign in once                                    | Provisioned by SeekOut; exchange credentials for a token     |

For user, administrator, and automated-workflow revocation, see [Revoking access](/mcp/security/overview#revoking-access).

<Tip>
  When in doubt, start with OAuth sign-in. It's simpler to set up and needs no provisioning step. Switch to M2M credentials only when your environment genuinely can't support an interactive sign-in flow.
</Tip>