# Share reports

> Give recipients access to a report and revoke access when needed.

Canonical: https://docs.georanker.com/docs/seo-tools-api-sharing

Use a share to give a client access to a report. The publishing integration manages the share with its account's bearer key. The recipient reads the report with a temporary share token and needs no GeoRanker API key.

## Create or update a share

Send `POST /api/shares` with the report UUID in `reportId` and its type in `reportType`. You can set a `password` and restrict access to addresses in `emails`. This example shows a rank tracker share restricted to one illustrative email address. Replace the UUID and email before running it.

```sh
curl --request POST 'https://seoapi.georanker.com/api/shares' \
  --header "Authorization: Bearer $SEO_TOOLS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"reportId":"130d9669-f1fd-4393-884b-38cff7fa17db","reportType":"rank_tracker","emails":["analyst@example.com"]}'
```

The success response is HTTP 200 with an `ok` boolean. Read the current settings with `GET /api/shares/{reportId}` using the same bearer authentication.

## Read a report as a recipient

* Get the share metadata from `GET /api/public/shares/{reportId}`. This request is unauthenticated. The response includes `reportType` and `hasPassword`.
* Exchange the credentials required by that share at `POST /api/public/shares/{reportId}/token`. The JSON body accepts `email` and `password`. A valid exchange returns HTTP 200 with a `token` string. Invalid credentials return HTTP 401.
* Send the temporary token in the `token` query parameter on the matching public report endpoint. Keep the token and token-bearing URLs private.

For the email-restricted rank tracker example, set `REPORT_ID` to the shared report UUID. The following commands use `jq` to read the token and `curl` to encode it in the results request.

```sh
SHARE_TOKEN=$(curl --fail --silent --show-error \
  --request POST "https://seoapi.georanker.com/api/public/shares/$REPORT_ID/token" \
  --header 'Content-Type: application/json' \
  --data '{"email":"analyst@example.com"}' | jq -er '.token')

curl --get "https://seoapi.georanker.com/api/public/ranktracker/$REPORT_ID/keywords" \
  --data-urlencode "token=$SHARE_TOKEN"
```

## Supported report types and public read paths

All paths below use `GET`. Substitute the shared report UUID for `{id}` and pass the token on each request.

| Value of `reportType` | Report                           | Additional results                                                                               |
| --------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------ |
| `rank_tracker`        | `/api/public/ranktracker/{id}`   | `/api/public/ranktracker/{id}/keywords` and `/api/public/ranktracker/{id}/keyword-serp/{serpId}` |
| `heatmap`             | `/api/public/heatmap/{id}`       | `/api/public/heatmap/{id}/results`                                                               |
| `serp_snapshot`       | `/api/public/serp-snapshot/{id}` | `/api/public/serp-snapshot/{id}/results`                                                         |
| `onpage`              | `/api/public/onpage/{id}`        | Report endpoint only                                                                             |
| `keyword_research`    | `/api/public/keywords/{id}`      | Report endpoint only                                                                             |

## Revoke a share

The publishing integration can revoke the share with `DELETE /api/shares/{reportId}` using its bearer key. A successful request returns HTTP 200 with an `ok` boolean.

[SEO Tools API overview](https://docs.georanker.com/docs/seo-tools-api)
