> ## Documentation Index
> Fetch the complete documentation index at: https://atmet.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Common Atmet Authentication and API Issues

> Diagnose and resolve the most common issues with authentication, integrations, workflows, and the Atmet API quickly and confidently.

Most issues with Atmet fall into one of four categories: authentication, integration connections, workflow behavior, and API errors. Work through the relevant section below to identify and fix the problem. If you're still stuck after following these steps, reach out via the in-app chat.

## Authentication Issues

<Accordion title="I can't sign in to my account">
  If you're unable to sign in, check each of the following in order:

  **Email domain not permitted**
  Some email domains are not permitted to access Atmet. If you receive a `403 Forbidden` error when attempting to sign in, your domain may be restricted. Try signing up with a different email address, or contact the Atmet team to request access for your domain.

  **OTP has expired**
  First-time users approved from the waitlist sign in with a one-time password (OTP) sent by email. OTPs are time-limited — if yours has expired, contact the Atmet team to request a new one.

  **OTP email not received**
  Check your **spam**, **promotions**, and **junk** folders. Email filtering can divert automated messages. Add `no-reply@atmetai.com` to your contacts to prevent future filtering.

  **Incorrect password**
  If you have an existing account and have forgotten your password, use the **Forgot Password** flow on the sign-in page to receive a reset link.
</Accordion>

<Accordion title="I need to reset my password">
  Follow these steps to reset your password:

  1. Go to the Atmet sign-in page.
  2. Click **Forgot your password?** below the sign-in form.
  3. Enter your email address and click **Send Reset Link**.
  4. Open the email from Atmet and click the reset link.
  5. Enter and confirm your new password.

  <Note>
    Password reset links expire after a short window. If your link has expired, restart the process from the sign-in page to receive a fresh link.
  </Note>
</Accordion>

<Accordion title="My invitation link has expired or doesn't work">
  Invitation links are single-use and time-limited. If the link you received no longer works:

  1. Contact the workspace **owner** or an **admin** and ask them to send a new invitation.
  2. The owner or admin navigates to **Settings → Members**, finds your pending invitation, and clicks **Resend** or issues a fresh invite to your email address.
  3. Use the new link promptly — don't let it sit in your inbox for extended periods.

  <Tip>
    If you are the owner and can't find a pending invitation in the Members list, simply send a brand-new invite to the same email address.
  </Tip>
</Accordion>

***

## Integration Connection Issues

<Accordion title="OAuth connection failed or returned an error">
  OAuth failures are usually caused by incomplete permission grants or a stale authorization session. Try the following steps:

  1. Go to **Settings → Integrations** and find the affected integration.
  2. Click **Disconnect** to revoke the existing connection.
  3. Click **Connect** again and go through the OAuth flow from scratch.
  4. On the third-party authorization screen, make sure you **grant all requested permissions**. Denying any scope can cause partial or failed connections.
  5. After reconnecting, test the integration by running a simple workflow that uses it.

  <Warning>
    If you're connecting a Google account, ensure you're authorizing the correct Google profile. Browser sessions with multiple Google accounts logged in can send you to the wrong one.
  </Warning>
</Accordion>

<Accordion title="My Telegram bot isn't receiving messages">
  Telegram bot issues are almost always a configuration problem. Work through this checklist:

  1. **Verify the bot token.** Go to **Settings → Integrations → Telegram** and confirm the token matches the one shown in [@BotFather](https://t.me/BotFather) for your bot. Tokens change when you regenerate them in BotFather.
  2. **Check the bot is in the right chat.** The bot must be added as a **member** of the group, channel, or direct conversation you want it to monitor. Bots cannot receive messages from chats they haven't been added to.
  3. **Check admin permissions (for groups).** If the bot needs to read all messages in a group, ensure it has the appropriate group admin permissions.
  4. **Disable privacy mode (if applicable).** By default, bots in groups only receive messages that start with `/`. To receive all messages, disable privacy mode via BotFather using `/setprivacy`.

  After making any change, send a test message to the chat and check the run log in Atmet for incoming activity.
</Accordion>

<Accordion title="An integration shows as Disconnected">
  Integrations can become disconnected when an authorization token expires, a password changes, or the third-party app revokes Atmet's access. To reconnect:

  1. Go to **Settings → Integrations**.
  2. Find the integration showing a **Disconnected** status.
  3. Click **Reconnect** and complete the authorization flow.
  4. Verify the integration is active by re-running any workflows that depend on it.

  <Info>
    Some services (for example, Google) periodically revoke access for apps that haven't been used recently or that haven't been verified. Re-authorizing Atmet restores access.
  </Info>
</Accordion>

***

## Workflow Issues

<Accordion title="My workflow isn't triggering">
  If a workflow is configured but not firing when expected, check the following:

  1. **Integration is connected and active.** Navigate to **Settings → Integrations** and confirm the integration the trigger depends on shows a connected status. A disconnected integration silently blocks triggers.
  2. **Trigger conditions match the incoming event.** Open the workflow, review the trigger configuration, and compare it against the actual event data. A filter that's too narrow — for example, matching on a specific sender or label — can prevent most events from firing the workflow.
  3. **Workflow is enabled.** Confirm the workflow's status toggle is set to **Active** in the workflow list.
  4. **Event actually occurred.** Check the source app to confirm the event happened as expected. Sometimes the upstream service delays or drops events.
</Accordion>

<Accordion title="My workflow is stuck in review">
  Some workflows include a human-in-the-loop step that requires explicit approval before continuing. If a run is stuck:

  1. Open the workflow from the dashboard.
  2. Navigate to the **Runs** tab and find the stuck execution.
  3. Look for a step labeled **Pending Approval** or **Awaiting Review**.
  4. Click the step and select **Approve** or **Reject** to unblock the run.

  <Note>
    Approval requests may also appear as a notification in the Atmet dashboard. Check the notification bell in the top navigation if you don't see the prompt inside the workflow.
  </Note>
</Accordion>

<Accordion title="My workflow ran but an action failed">
  A workflow can trigger and run partially — completing some steps while failing on others. To diagnose a failed action:

  1. Open the workflow and go to the **Runs** tab.
  2. Click the failed run to expand the step-by-step log.
  3. Find the step marked with a red error indicator and read the error message. Common causes include:
     * **Integration permission revoked** — the connected account no longer grants the required scope. Reconnect the integration.
     * **Invalid or missing input data** — a required field was empty or formatted incorrectly. Check the data mapping in the workflow step.
     * **Rate limit hit on the third-party service** — the external API refused the request. Add a delay or retry policy to the step.
  4. Fix the identified issue and click **Re-run** to retry the failed execution from the beginning.
</Accordion>

***

## API Issues

<Accordion title="401 Unauthorized">
  A `401` response means your API key is missing, malformed, or no longer valid. Check the following:

  * Confirm the `Authorization` header is formatted correctly: `Authorization: Bearer atmet_your_key_here`
  * Check that the key hasn't been revoked in **Settings → API Keys**
  * Verify you are not accidentally including extra whitespace or line breaks in the key value
  * If the key has expired (you set an expiry date at creation), generate a new key

  If the key looks correct and is still listed as active, try revoking it and generating a fresh one.
</Accordion>

<Accordion title="403 Forbidden">
  A `403` response means your request was received but the action is not permitted. There are two common causes:

  **Insufficient permissions**
  Your workspace role does not allow the requested action. For example, only owners and admins can update workspace settings. Check your role in **Settings → Members** and ask an owner or admin to adjust it if needed.

  **Email domain not permitted**
  If your account's email domain is restricted, certain actions will return a `403`. Contact the Atmet team if you believe this is a mistake and need your domain approved.
</Accordion>

<Accordion title="404 Not Found">
  A `404` response usually means the resource identifier in the request is wrong. The most common cause when calling workspace-scoped endpoints is a missing or incorrect `x-workspace-id` header.

  * Add the `x-workspace-id: your_workspace_id` header to your request
  * Confirm the workspace ID by checking your workspace URL in the dashboard or by calling `GET /api/workspaces` and reading the `id` field from the response
  * Verify the endpoint path is correct and that the resource (for example, a specific API key or member) actually exists in the workspace
</Accordion>

<Accordion title="429 Too Many Requests">
  A `429` response means you have exceeded the API rate limit for your workspace plan. To resolve this:

  * **Reduce request frequency.** Add delays between calls, especially in loops or batch operations.
  * **Implement exponential backoff.** When you receive a `429`, wait before retrying — start with 1 second, then 2, 4, 8, and so on.
  * **Cache responses where possible.** If you're polling for data that doesn't change frequently, store the last response and reduce how often you call the API.
  * **Review your usage plan.** If your integration genuinely needs higher throughput, contact the Atmet team to discuss a higher-tier plan.

  <Tip>
    Check the `Retry-After` header in the `429` response — it tells you exactly how many seconds to wait before making your next request.
  </Tip>
</Accordion>