> For the complete documentation index, see [llms.txt](https://docs.prophetmarket.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.prophetmarket.ai/api/authentication.md).

# Authentication

Nothing on the public market data surface requires credentials. Authentication becomes necessary for reading anything belonging to a specific account, for trading, and for creating markets.

## Two mechanisms

The API accepts session tokens issued through the sign-in flow, and separately supports long-lived HMAC credentials intended for programmatic access.

| Mechanism     | Obtained by                                        | Suited to                               |
| ------------- | -------------------------------------------------- | --------------------------------------- |
| Session token | Signing in to the application                      | Browser clients, short-lived sessions   |
| HMAC key pair | Registering credentials against a signed challenge | Scripts, bots, server-side integrations |

Session tokens are supplied in the `Authorization` header. The sign-in providers used by the application issue these, so a browser-based integration inherits them from the existing session rather than requesting them separately.

## Registering API credentials

The programmatic path is a challenge-and-signature exchange. It proves control of the account's key without transmitting it, and it produces a key pair you can store.

The flow has two calls. First, request a challenge. Note that this one is a **query**, not a mutation, which is easy to get wrong:

```graphql
query {
  generateApiChallenge {
    nonce
    timestamp
    action
    domain { name version chainId }
  }
}
```

The response carries the `nonce`, `timestamp` and `action`, plus an `EIP712Domain` containing `name`, `version` and `chainId`. Assemble those into an EIP-712 typed data structure and sign it with the account's externally owned address, then submit the signature as a mutation:

```graphql
mutation Register($signature: String!, $nonce: String!, $timestamp: String!) {
  registerApiCredentials(
    signature: $signature
    nonce: $nonce
    timestamp: $timestamp
  ) {
    apiKey
    apiSecret
  }
}
```

The server verifies that the signature recovers to the account's address and returns an `ApiCredentialResult` containing `apiKey` and `apiSecret`.

{% hint style="danger" %}
**The API secret is shown exactly once**

It is returned by `registerApiCredentials` and never again. Capture it at the moment of creation and store it somewhere durable and secret. If it is lost, the only recovery is to register new credentials.
{% endhint %}

Both calls require a valid session token, so credential registration is bootstrapped from an authenticated session rather than being available anonymously.

## What authentication unlocks

Once authenticated, the account-scoped surface becomes available: positions and claimable positions, balances, order history, transaction records, profile status, and the five user-scoped [subscriptions](broken://pages/846e4bcf7069a45159906352eef7cf8d1c3201c5).

Trading requires more than a token. Placing an order that settles on-chain follows a signing flow: request signing parameters with `orderParams`, sign the resulting EIP-712 structure, and submit it with `submitSignedOrder`. The simpler `placeBet` and `placeOrder` mutations exist for order book interaction, and both require a verified email address and a sufficient balance in addition to a token.

Market creation runs through its own sequence: `initiateMarket` validates the question, `startOddsCalculation` begins pricing, `oddsCalculationSession` is polled for progress, `marketCreationOrderParams` returns signing parameters for the initial position, and `createMarketWithBet` completes it.

{% hint style="warning" %}
**`createMarketWithBet` is described in the schema as simulated for MVP**

The field's own description marks it as simulated. Treat market creation through the API as provisional, and verify behaviour against a real market before relying on it in production.
{% endhint %}

## Geographic restriction

`geoCheck` returns the country associated with the requesting IP address and whether it is blocked, and requires no authentication.

```graphql
{
  geoCheck { country blocked }
}
```

Because restriction is evaluated against the request's origin, a server-side integration is judged on the server's location rather than the user's. See [Availability](file:///7444037/availability.md) for which jurisdictions are excluded.

## Errors

An unauthenticated request to a protected field returns HTTP 200 with a `UNAUTHORIZED` message and a null data payload, as described in [Conventions](broken://pages/97c6f664f215a634c792ddab5b052b71c59b327d). There is no distinct status code and no error code beyond the message string, so match on that message for the authentication case specifically.

## What is not documented

There is no published policy on token lifetime, credential rotation, revocation, or scoping of API credentials to particular permissions. The public [API page](https://prophetmarket.ai/api) states only that access "may require authentication depending on the resources being requested". Until that is documented, treat credentials as long-lived and unscoped, store them accordingly, and register separate credentials per integration so that one can be abandoned without affecting the others.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.prophetmarket.ai/api/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.