# Sharelinks

https://api-docs.lumar.io/docs/graphql/sharelinks

Sharelinks allow you to generate time-limited, read-only access links to project data. They are useful for sharing crawl results with stakeholders who do not have a Lumar account.

## What sharelinks are

A sharelink is a URL that grants temporary access to a project's data. Each sharelink:

- Is scoped to a specific project.
- Has an expiration date (`expiresAt`).
- Can optionally target a specific URL within the Lumar application (`targetUrl`).
- Includes an authentication token for the recipient.

## Creating a sharelink

Use the `shareProject` mutation to generate a new sharelink. The mutation returns both the sharelink details and an authentication token.

```graphql
mutation ShareProject($input: ShareProjectInput!) {
  shareProject(input: $input) {
    authToken {
      value
    }
    sharelink {
      id
      targetUrl
      createdAt
      sharelinkTemplate {
        code
        name
      }
    }
  }
}
```

**Variables:**
```json
{
  "input": {
    "projectId": "TjAwN1Byb2plY3Q2MTMy",
    "expiresAt": "2025-06-01T00:00:00.000Z",
    "targetUrl": "https://app.lumar.io/projects/123/overview"
  }
}
```

**Response:**
```json
{
  "data": {
    "shareProject": {
      "authToken": {
        "value": "share_81372d5bd83919e791be3fe06cdf2b7e760eebe5..."
      },
      "sharelink": {
        "id": "TjAzN1NoYXJlbGluazE",
        "targetUrl": "https://app.lumar.io/projects/123/overview",
        "createdAt": "2025-01-15T10:00:00.000Z",
        "sharelinkTemplate": {
          "code": "default",
          "name": "Default"
        }
      }
    }
  }
}
```

The `authToken.token` value can be appended to the target URL to grant the recipient access without requiring them to log in.

## Querying sharelinks

Retrieve the existing sharelink for a project:

```graphql
query GetSharelink {
  sharelink {
    id
    createdAt
    targetUrl
  }
}
```

**Variables:**
```json
{
  "projectId": "TjAwN1Byb2plY3Q2MTMy"
}
```

**Response:**
```json
{
  "data": {
    "sharelink": {
      "id": "TjAzN1NoYXJlbGluazE",
      "createdAt": "2025-01-15T10:00:00.000Z",
      "targetUrl": "https://app.lumar.io/share/abc123"
    }
  }
}
```

## Access control

- **Expiration** -- sharelinks automatically expire at the date specified in `expiresAt`. After expiration, the link returns an authentication error.
- **Read-only** -- sharelink recipients can view data but cannot modify projects, run crawls, or change settings.
- **Single project scope** -- each sharelink grants access only to the specific project it was created for.
- **Revocation** -- to revoke a sharelink before its expiration, you can update the project settings or contact support.