How to test in other environments

Environments

Deal Engine's GraphQL API runs in two confirmed environments (Production and Sandbox) each available on two tenants (US and EU):

• Use your tenant's URL for the environment you want to test.
• If you've been given an endpoint under another name (e.g. "development," "staging," "cert," "UAT"), see Environments & access for how those aliases map to Production/Sandbox above.

Role-based schema visibility in Apollo Sandbox

The GraphQL schema shown in Apollo Sandbox is role-aware.

If you open the Sandbox without authentication, Apollo will only display public queries and mutations, such as login. To see the queries, mutations, and fields available to your role:

1. Run the login mutation or obtain an access token for the target environment.
2. Add the header:

Authorization: Bearer <token>

3. Click Refresh Schema in Apollo Sandbox.
4. Open the Docs/Explorer panel again.

If a query or mutation is still not visible after refreshing the schema, verify that:

• The token belongs to the same environment as the endpoint.
• The token has not expired.
• Your user’s role includes permission for that operation.

Option A: Built-in Apollo Sandbox (when enabled)

In environments where the landing page is enabled, simply open the GraphQL endpoint in your browser. You’ll see Apollo Sandbox with schema introspection, an editor, and a place to add headers.

Steps:

1. Navigate to your environment’s GraphQL URL in a browser.
2. In the “Headers” panel, add an auth header to load the operations available to your role:
   • Key: Authorization
   • Value: Bearer <accessToken>
3. Click Refresh Schema so Apollo reloads the operations available to your role.
4. Run queries and mutations directly in the editor.

Option B: Hosted Apollo Sandbox

If the built-in landing page is disabled, use Apollo’s hosted explorer and point it at your endpoint.

Steps:

1. Open Apollo Sandbox (hosted) in your browser.
2. In the Endpoint field, paste your environment’s GraphQL URL.
3. In the “Headers” panel, add:
   • Authorization: Bearer <accessToken>
4. Click Refresh Schema after adding the Authorization header. This is required for Apollo to reload the schema with the operations allowed by your role.

Getting a Token for Testing

Use the login mutation to obtain tokens. You can run it in the Sandbox without an Authorization header, then use the returned token for subsequent requests.

mutation Login($email: String!, $password: String!) {
    login(email: $email, password: $password) {
        token
        refreshToken
        expiresIn
    }
}

After login, copy the token and set the header:

Authorization: Bearer <token>

To refresh an expired access token, you can use:

mutation RefreshToken($refreshToken: String) {
    refreshToken(refreshToken: $refreshToken) {
        token
        refreshToken
        expiresIn
    }
}

If your environment sets secure cookies on login, the Sandbox may authenticate via cookies automatically (browser dependent). For consistency across environments, prefer the Authorization header.

Quick Checks

• Query the current user:

query User {
    user {
        id
        email
    }
}

• Fetch a document by ticket number:

query Document($ticketNum: String!) {
    document(ticketNum: $ticketNum) {
        id
        ticketNum
        status
    }
}

Troubleshooting

• “Unauthorized” errors: Ensure the Authorization header is present and the token is valid.
• Schema won’t load: Confirm the endpoint URL and that introspection is allowed in that environment.
• Cookies not applied: Rely on the header-based token instead of cookies, especially across subdomains.
• CORS errors: Use the Sandbox from a browser that can reach the endpoint; for server-to-server tests, use curl or Postman.

Best Practices

• Keep separate tokens per environment; do not reuse production credentials in lower envs.
• Always set the Authorization header explicitly in the Sandbox for predictable behavior.
• Validate filters and pagination in Sandbox before integrating into your app.