--- title: Frequently asked questions description: Answers about the Signal and GPS REST APIs, webhooks, MCP connectors, security and limits. product: all section: faq order: 0 --- # Frequently asked questions ## Getting started ### What can I build on Empiraa? Two products, each with two ways in. Signal is the CRM and GPS is the business operating system. Each has a REST API with webhooks for code you write, and an MCP connector for AI assistants. See [Use cases](../use-cases/index.md). ### Should I use the REST API or the MCP connector? Use the REST API when your own code or an automation tool makes the calls. Use the MCP connector when a person works in Signal or GPS from an AI assistant such as Claude or ChatGPT. The API signs in with a key and acts as the workspace or organization. The connector signs each person in and acts as them. ### What is MCP? MCP is the open standard AI assistants use to connect to business apps. Signal and GPS each run an MCP connector, so an assistant can read your records and, if you allow it, make changes. ### Where do I start with Signal? The [Signal quickstart](../signal/api/index.md) takes about five minutes: create a key, call `GET /me`, then create an Account. To connect an assistant instead, see [Connecting your assistant](../signal/mcp/connecting.md). ### Where do I start with GPS? The [GPS quickstart](../gps/api/index.md) takes about five minutes: create a key, list your Goals, then record a check-in. To connect an assistant instead, see [Connecting your assistant](../gps/mcp/connecting.md). ### Is there an OpenAPI file? Yes, one for each API. Download them from the [Signal API explorer](../signal/api/explorer.html) and the [GPS API explorer](../gps/api/explorer.html), or browse every endpoint there. ### Can I point an AI coding tool at these docs? Yes. Every page is also available as Markdown: swap `.html` for `.md` in the address. There's an index of every page at `/llms.txt`. ### Is there a sandbox or test environment? Not yet. Build against your own workspace or organization. Start with a read-only key, and use test records you can delete afterwards. ## API keys and sign-in ### How do I create a Signal API key? In Signal, open **Autopilot**, select the **Webhooks & API** tab, then **API Keys** and **New Key**. Name it, tick the scopes it needs and copy the key. Signal shows the full key only once. See [Signal authentication](../signal/api/authentication.md). ### How do I create a GPS API key? In GPS, open **Settings → Developer → Keys & Webhooks** and select **New API Key**. Copy both the API key and the secret. The secret is shown only once. You need the Owner, Super Admin or Admin role. See [GPS authentication](../gps/api/authentication.md). ### How do I send the key? Signal: send `Authorization: Bearer YOUR_API_KEY`, or the same key in an `X-API-Key` header. GPS: send two headers, `X-API-Key` and `X-API-Secret`. ### What do the keys look like? A Signal key starts with `sk_live_`. A GPS key starts with `emp_` and comes with a separate secret. ### I lost my key. Can I get it back? No. Signal keeps only a hash of the key, and GPS keeps only a hash of the secret. Create a new key and revoke the old one. ### Do keys expire? Signal keys don't expire. They work until you revoke them. A GPS key can have an optional expiry date, set when you create it. ### What are scopes? A scope limits what a key can do, such as `deals:read` or `goals:write`. Give each key only the scopes its job needs. A request outside a key's scopes answers `403 INSUFFICIENT_SCOPE`. ### Who does a key act as? A Signal key stands for the workspace, not a person, so records it creates have no owner unless you send `owner_id`. A GPS key attributes records to the member who created the key, unless you send `onBehalfOf` with another member's ID. ### Can one key reach more than one workspace or organization? No. A key reads and writes only the workspace or organization it was created in. ### Can I call the API from a browser? Keep keys on your server. A key in browser code can be read by anyone who opens the page. ## Requests and responses ### What's the base URL? Signal: `https://crm.empiraa.app/api/v1`. GPS: `https://plan.empiraa.app/api/v1`. ### What format do requests and responses use? JSON over HTTPS. Send `Content-Type: application/json` on requests with a body. Successful responses put the result under `data`. ### Why are Signal's fields snake_case and GPS's camelCase? They're separate products with their own APIs. Signal uses `snake_case` field names. GPS uses `camelCase`. Each API's conventions page has the details. ### How does paging work in Signal? Most lists use a cursor. Ask for up to 100 records with `limit`, and when `meta.hasMore` is `true`, pass `meta.cursor` back as `cursor` for the next page. Prospect Companies use `limit` and `offset` instead. See [Signal conventions](../signal/api/conventions.md#pagination). ### How does paging work in GPS? Every list takes `limit` (up to 200) and `offset`. `meta.total` tells you how many records match. See [GPS conventions](../gps/api/conventions.md#pagination). ### Can I search or sort a list? Signal lists take exact-match filters and have a fixed order, newest first unless a page says otherwise. There's no free-text search or sort parameter. GPS lists take filters, and you sort on your side. ### How do I update just one field? Use `PATCH` and send only that field. Fields you leave out keep their values. ### How are dates and money sent? Timestamps are ISO 8601 in UTC. Signal amounts are numbers in the workspace's currency, which `GET /me` returns. ### Can I use custom fields through the API? In Signal, yes, on prospect contacts, developments and plots. Send them in a `custom_fields` object keyed by each field's internal name. See [Custom fields](../signal/api/conventions.md#custom-fields). ### What does an error look like? Signal uses the problem details format with a stable `code`, such as `NOT_FOUND`. GPS returns `error`, `code` and, for validation failures, an `issues` array naming each field. In both, build your handling on `code`, not on the message text. ### Why do I get 404 for a record I know exists? The record is probably in another workspace or organization. Both APIs answer `404` for those, the same as for an ID that doesn't exist. In GPS, archived Goals, Objectives and Meetings also answer `404`. ## Limits and reliability ### Are there rate limits? GPS allows 100 requests a minute for each API key. Past that it answers `429` with a `Retry-After` header. Signal allows 1,000 requests a minute for each API key and answers the same way. See [Signal rate limits](../signal/api/conventions.md#rate-limits) and [GPS rate limits](../gps/api/conventions.md#rate-limits). ### What should I do when I get a 429? Wait for the number of seconds in `Retry-After`, then try again. ### How do I retry safely? In Signal, send an `Idempotency-Key` header on creates. Retries with the same key create the record only once. GPS doesn't support idempotency keys, so before retrying a create, list the records to check whether the first attempt landed. ### How do I avoid duplicate prospect contacts? `POST /prospects` in Signal matches on email. Sending the same person twice updates them instead of creating a duplicate. ### Can I undo a delete? No. Deleting through the API is permanent. ### How will I know about breaking changes? The version is in the path (`/api/v1`). New fields can be added at any time, so ignore fields you don't recognize. Each connector also has a changelog and a versioning page. ## Webhooks ### What are webhooks for? They let Signal or GPS tell your systems the moment something changes, so you don't have to poll. See [Signal webhooks](../signal/api/webhooks.md) and [GPS webhooks](../gps/api/webhooks.md). ### How do I know a webhook really came from Empiraa? Check the signature. Every delivery carries `X-Empiraa-Signature`, an HMAC-SHA256 made with your webhook's signing secret. Each webhooks page has a working example. ### Are Signal and GPS signatures the same? No. Signal signs the timestamp and the raw body joined with a period. GPS signs the raw body only. Use each product's own example. ### How fast does my endpoint need to answer? Within 10 seconds for Signal. Return a `2xx` as soon as you've verified and stored the event, then do the work in the background. ### Are failed deliveries retried? GPS makes up to 3 attempts for each event, then drops it. For Signal, see [Delivery, timeouts and retries](../signal/api/webhooks.md). ### Can I get the same event twice? Yes. Record each event's ID and ignore repeats. ### Can I send a webhook straight to Zapier, Make or n8n? Yes. Use the catch-hook URL your tool gives you as the webhook's address. See [REST API and automation tools](../use-cases/rest-api.md). ## MCP connector ### Which assistants work with Signal and GPS? Claude and ChatGPT, plus any MCP client that supports remote servers with OAuth sign-in, such as Claude Code, Cursor and VS Code with GitHub Copilot. ### Do I need an API key for the connector? No. Each person signs in with their own Signal or GPS account and approves the connection. ### What are the connector URLs? Signal: `https://crm.empiraa.app/mcp`. GPS: `https://plan.empiraa.app/mcp`. ### How long does it take to connect? About a minute for each product. See the [Claude](../use-cases/claude.md) and [ChatGPT](../use-cases/chatgpt.md) guides. ### Can I use both connectors in one chat? Yes. Turn both on and the assistant can use them together, for example to take sales figures from Signal into a check-in in GPS. ### What's the difference between View only and View and make changes? View only lets the assistant read what you can see. View and make changes also lets it create and update records, as you. You choose when you approve the connection. ### Does it work with Grok? A Grok bot built on the xAI API can use the REST API through function calling, or the connector with a token your app holds. See [Grok bots](../use-cases/grok.md). ### Does it work with OpenClaw? Yes. OpenClaw supports remote MCP servers with OAuth sign-in. See [OpenClaw bots](../use-cases/openclaw.md). ### Is there a list of prompts to try? Yes. The [Prompt library](../prompts/index.md) has copy-and-paste prompts for both products. ### Where's the full list of tools? The [Signal tool reference](../signal/mcp/tools.md) has 51 tools and the [GPS tool reference](../gps/mcp/tools.md) has 110. ## Tokens and headless agents ### How long do connector tokens last? An access token lasts 1 hour. A refresh token lasts 30 days without use, and each use restarts the 30 days. ### Why does my refresh token change every time I use it? Refresh tokens rotate. Each refresh returns a new access token and a new refresh token, and the old refresh token stops working. This limits the damage if a token is ever stolen. ### Do I need to refresh on every session? No. The connector is stateless, so one access token works for any number of calls and sessions until it expires. Refresh only when it's about to expire, or after a `401`. ### My agent needs a restart every time the token rotates. How do I avoid that? Don't pass tokens in environment variables, because a process reads those only at start. Keep the tokens in one store owned by a small broker, and have each agent ask it for the current access token at call time. See [Headless agents and token refresh](../use-cases/headless-agents.md). ### Two of my agents share a connection and it keeps getting disconnected. Why? They're probably both refreshing. The second one presents a refresh token that has already been rotated, and outside a 30-second window that's treated as theft, so the connection is revoked. Let one process own the refresh. ### What happens if a refresh response is lost? Retry with the same refresh token within 30 seconds, from the same client. You get a fresh pair. ### Can I use an API key with the connector? No. The connector accepts OAuth access tokens only. For unattended jobs that do a set thing, use the REST API with an API key. ### Why was my connection paused? Signal and GPS pause a connection that makes an unusual number of changes or errors, in case it's stuck in a loop. Select **Resume** beside it in your connected apps. ## Safety and permissions ### Can an assistant see everything in our account? No. It works as the person who connected it and sees only what their role lets them see. ### Can an assistant delete records? In Signal, no. It can undo its own changes. In GPS, no, except removing an empty position from your org chart. ### Will an assistant change things without asking? Changes are shown first. In Signal, every change is previewed as a card and your assistant app asks before applying it. In GPS, batches are previewed first. ### Can I undo a change an assistant made? Usually, within 7 days. Some changes can't be undone, and they say so up front. See [Signal safety](../signal/mcp/safety.md) and [GPS safety](../gps/mcp/safety.md). ### Can an assistant email my customers? Signal's connector never emails anyone but the person who connected it. It drafts, and sending stays with people in Signal. In GPS, five tools reach people by email or calendar invite, and each says so in its description. ### How do I see what an assistant changed? Signal records every change in **Settings › AI activity**. GPS labels each change with the app, such as "via Claude", and lists them in **Connected apps**. ### Can an admin turn assistants off? Yes. Admins can turn assistants off for a whole Signal workspace or GPS organization, or limit them to View only. See [Signal admin controls](../signal/mcp/admin-controls.md) and [GPS admin controls](../gps/mcp/admin-controls.md). ### How do I disconnect an assistant? Signal: **Settings › Integrations › AI assistants**. GPS: **Settings › Profile › Connected apps**. Select **Disconnect**. Changing your password also disconnects every app. ### What if a note or email tells the assistant to do something? In Signal, text that came from a record, an email or a Form reaches the assistant marked as untrusted data, so it can be told apart from your own requests. See [Signal safety](../signal/mcp/safety.md). ## Data and privacy ### Does Empiraa see my conversation with the assistant? No. GPS receives only the name of each tool your assistant calls and the arguments it sends. What it returns goes to your assistant's provider, under your agreement with them. See [GPS data and privacy](../gps/mcp/safety.md). ### Is my data used to train AI models? No. Empiraa doesn't use the data an assistant reads or writes through the Signal or GPS connector to train AI models. Your assistant provider (for example Anthropic or OpenAI) has its own data terms for what the assistant sees, so check those too. ### Are keys and tokens stored safely? Signal stores only a hash of each API key. GPS stores only a one-way hash of each key's secret, and only a hash of each connector access token. ## Plans and support ### Does the connector cost extra? No. The connector is included on every Signal plan and every GPS plan. Each person also needs their own plan with their assistant app, for example Claude or ChatGPT. ### Does the API cost extra? No. API access is included on every Signal plan and every GPS plan. ### Where do I get help? Email [team@empiraa.com](mailto:team@empiraa.com). Say which product, which endpoint or tool, and what came back. ### Where do I report a bug in the docs? Email [team@empiraa.com](mailto:team@empiraa.com) with the page and what's wrong.