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

# Set secrets and test an app

> Sign in to an app as yourself, call its API, give it credentials, and find its failing calls.

Complete [Build and deploy an app](https://docs.canary.effectiveai.app/guides/apps/build-an-app.md) first. Signing in and calling the app
need `publish` permission on it; setting secrets and reading its calls need `build`.
[Get an app](https://docs.canary.effectiveai.app/api-reference/apps/get-an-app.md) lists yours in `permissions`.

The examples continue with `app-claims-notes`. Values in them are illustrative.

## Sign a browser in

Open the app's `url` from [Get an app](https://docs.canary.effectiveai.app/api-reference/apps/get-an-app.md). A browser that isn't signed
in is redirected to an `/app-authorize` URL. Copy it from the address bar and pass it as
`authorizeUrl`:

```bash theme={null}
curl --request POST \
  --url "https://api.canary.effectiveai.app/api/v2/apps/app-claims-notes/sign-ins" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "authorizeUrl": "<the /app-authorize URL>" }'
```

```json theme={null}
{
  "callbackUrl": "https://…",
  "callbackExpiresAt": "2026-10-26T18:10:05.000Z",
  "signInExpiresInSeconds": 600
}
```

Open `callbackUrl` in the same tab within a minute; it doesn't work in another tab or browser. The
app loads signed in as you for ten minutes.

## Call the app's API

To test a backend route without a browser, send one request to it, signed in as you:

```bash theme={null}
curl --request POST \
  --url "https://api.canary.effectiveai.app/api/v2/apps/app-claims-notes/calls" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "method": "GET", "path": "/api/health" }'
```

```json theme={null}
{
  "status": 200,
  "contentType": "application/json",
  "body": "{\"ok\": true, \"appId\": \"app-claims-notes\", \"userId\": \"123\"}",
  "truncated": false
}
```

`status` and `body` are the app's own response, so a `200` from Effective can carry the app's
`404` or `500`. `502` with `app_unreachable` means the app timed out or couldn't be reached, and it
may have run the request; Effective doesn't retry, so repeat it only if that's safe.

When the app calls Effective for you, it has no more access than your API key.

## Set a secret

An app's code never holds a secret. Effective adds the value to the app's outbound HTTPS requests
to the hosts you name. This stores `weather-key` and sends it to `api.weather.example` in an
`X-Api-Key` header:

```bash theme={null}
curl --request PUT \
  --url "https://api.canary.effectiveai.app/api/v2/apps/app-claims-notes/secrets/weather-key" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "value": "'"$WEATHER_API_KEY"'",
    "routes": [{ "host": "api.weather.example", "headerName": "X-Api-Key" }]
  }'
```

The response describes the secret without its value, with `"configured": true`. The app uses it
from its next request; you don't need to deploy again. To change the value or routes, send the PUT
again with both. See [Set an app secret](https://docs.canary.effectiveai.app/api-reference/apps/set-an-app-secret.md) for other header
formats.

## Find failing calls to Effective

When the app's requests to Effective fail, list them, newest first:

```bash theme={null}
curl --request GET \
  --url "https://api.canary.effectiveai.app/api/v2/apps/app-claims-notes/api-calls?failedOnly=true" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

```json theme={null}
{
  "calls": [
    {
      "at": "2026-10-26T18:12:40.000Z",
      "method": "GET",
      "path": "/api/v2/insurance/managed-filings",
      "status": 403,
      "durationMs": 41
    }
  ]
}
```

A `403` means the signed-in user, or the API key they signed in with, can't use that route. The
list covers the last hour, and calls can take a minute to appear. See
[List app API calls](https://docs.canary.effectiveai.app/api-reference/apps/list-app-api-calls.md) to read further back.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.