# Authentication & Security 



Learn how Astravue MCP authenticates your AI client and keeps your workspace secure.

---

## How authentication works

Astravue MCP uses **OAuth 2.0 Authorization Code Flow with PKCE** — the same secure standard used by Google, GitHub, and Slack integrations.

<Steps>

<Step title="Your AI client requests access">

When you add Astravue MCP to your client, it generates a secure one-time code challenge (PKCE) and redirects you to the Astravue sign-in page in your browser.

</Step>

<Step title="You sign in and approve">

You log in with your Astravue account and click **Approve**. Astravue issues an authorization code to your AI client.

</Step>

<Step title="Your client receives a token">

Your AI client exchanges the authorization code for an access token and refresh token. All future requests use the access token.

You only need to sign in again if the refresh token expires or access is revoked.

</Step>

</Steps>

:::info
Your Astravue password is **never shared with your AI client**.  
The AI client only receives a scoped access token issued through OAuth.
:::

---

## Authorization flow

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant Client as AI Client (Claude / Cursor / etc.)
    participant Auth as Astravue Auth 
    participant MCP as Astravue MCP (api.astravue.com/mcp)

    User->>Client: Add Astravue MCP server
    Client->>Client: Generate PKCE (code_verifier + code_challenge)

    Client->>Auth: Authorization request + code_challenge
    Auth-->>User: Redirect to Astravue sign-in page

    User->>Auth: Enter credentials and approve
    Auth-->>Client: Authorization code

    Client->>Auth: Exchange code + code_verifier
    Auth-->>Client: Access token + Refresh token

    loop Every MCP tool call
        Client->>MCP: Authorization: Bearer access_token
        MCP-->>Client: Tool response
    end

    Note over Client,Auth: Access token expires after 30 minutes
    

    Client->>Auth: Refresh token request
    Auth-->>Client: New access token + New refresh token
```

---

## Token lifecycle


| Token | Lifetime | Purpose |
|-------|----------|---------|
| Access token | 30 minutes | Authorizes every MCP tool call |
| Refresh token | Up to 30 days | Issues a new access token silently |

When an access token expires, your AI client automatically uses the refresh token to obtain a new one.

:::info
Astravue uses **refresh token rotation**.
Each refresh request issues a new refresh token and invalidates the previous one.
:::


---

## What the AI client can access

Access is determined entirely by your Astravue account permissions.

The AI can only:

- Read and modify data your account already has access to
- Perform actions allowed by your workspace role (member, admin, owner)
- Access projects where you are a member

:::tip
To limit what an AI assistant can access, adjust your **workspace role or project memberships** rather than modifying the MCP connection.
:::

---

## Disconnecting an AI client

You can remove Astravue MCP from your AI client at any time.

:::warning
Disconnecting removes the stored tokens from your AI client.
The access token remains valid until it expires (up to 30 minutes) but your client can no longer use it.
:::

To disconnect:

1. Open your AI client settings  
2. Locate the **Astravue MCP server connection**  
3. Remove or disable the server entry  

Your client will no longer be able to execute any MCP tools.

---

## Security best practices

<AccordionGroup>

<Accordion title="Use project-scoped connections when sharing config files">

If you commit an `.mcp.json` or `.cursor/mcp.json` file to a repository, each team member must authenticate individually with their own Astravue account.

**Note:** These configuration files only contain the MCP server URL. No credentials or access tokens are stored in them.


</Accordion>

<Accordion title="Review AI actions before approving in shared workspaces">

Enable tool approval mode in your AI client so write operations (create, update, delete) require confirmation before execution.

</Accordion>

<Accordion title="Revoke access when offboarding team members">

When a team member leaves your organization, remove their workspace access and ensure their MCP connections are revoked.

</Accordion>

<Accordion title="Never share access tokens">

Astravue MCP never requires manually copying tokens.

If a script or tool asks you to paste your Astravue access token, do not proceed.

</Accordion>

</AccordionGroup>

---

## Data in transit

| Security Feature | Details |
|------------------|--------|
| Encryption | TLS 1.2+ encryption for all traffic |
| Authorization header | `Authorization: Bearer <access_token>` |
| Data storage | MCP server does not store workspace content |

---

## Single Sign-On (SSO)

If your organization uses SSO, the Astravue MCP OAuth flow automatically redirects through your identity provider.

No additional configuration is required.

Users simply authenticate with their SSO credentials when connecting their AI client.

For enterprise SSO setup, contact **support@astravue.com**.