See ContextQA test your application in 30 minutes.
Book a free demo
Ctrlk
PlatformBook a DemoPricing
For the complete documentation index, see llms.txt. This page is also available as Markdown.

API Tokens

Create, scope, and manage API tokens in ContextQA — long-lived credentials for scripts and integrations, with exact route scopes, expiry, and an IPv4 or IPv6 allowlist.

Quick answer

Create a token under Settings → API Tokens, grant only the routes the integration calls, and optionally restrict it to exact IPv4 or IPv6 addresses. The token value appears once; copy it directly into an approved secret store.

What this page covers

Who is this for? SDETs, developers, and administrators who need to call the ContextQA API from scripts, CI/CD pipelines, or other integrations.

API tokens are scoped, long-lived credentials that authenticate automated calls to the ContextQA API. Each token carries a fixed set of permission scopes, an expiry, and an optional IP allowlist, so you can grant an integration exactly the access it needs and no more.

Open Settings → API Tokens to manage them. You only see tokens you created — each entry lists its name, creator, permissions, expiry, last use, and status.

API Tokens page with search, status filtering, rate limits, and the Create token action

API tokens are separate from the organization-level API key and secret shown under Settings → Authentication Configuration, and from the OAuth sign-in used by the ContextQA MCP Server. Use an API token when a script or integration needs its own scoped, revocable credential.

Key concepts

  • Scopes. Each token grants one or more permission scopes. A scope maps to fixed collection and item routes — for example, View Test Cases allows GET /test_cases and GET /test_cases/{test_case_id}. At least one scope is required.

  • Expiry. A token expires after a preset period, up to a maximum of 180 days. You can also create a token that never expires, though this is not recommended.

  • IP allowlist. By default a token accepts calls from any IP address. You can restrict it to exact IPv4 or IPv6 addresses; the allowlist is enforced before authentication.

  • One-time value. The token value appears only once, immediately after you create it. ContextQA does not store it in a readable form, so it cannot be recovered later.

  • Status. A token is Active, Deactivated, or Expired. You can deactivate and reactivate a token without deleting it.

Only superadmins can create tokens. If your role can't create tokens, the Create token button is hidden, but you can still manage tokens you already own.

Create a token

  1. Go to Settings → API Tokens.

  2. Click Create token.

  3. In the Details section, enter a recognizable Name (for example, CI Pipeline). The name can be up to 255 characters.

  4. From the Expires dropdown, select an expiry period. The default is 30 days.

  5. In the Permissions section, select the scopes the token needs. Pick the narrowest set that works. See Permission scopes for the full list.

  6. (Optional) In the IP allowlist section, restrict the token to specific IP addresses. See Restrict a token to specific IPs.

  7. Click Create token.

API token permission rows with exact API routes and an IPv4 or IPv6 allowlist

ContextQA creates the token and opens the Token created dialog with the token value.

The name and expiry can't be changed after a token is created — only its permissions and IP allowlist are editable. To change the name or expiry, create a replacement token and delete the old one.

Copy and store the token value

When the Token created dialog appears:

  1. Click Copy to copy the token value.

  2. Store it in an approved secret manager or your integration's secure configuration.

  3. Select the I have copied the token and stored it somewhere safe checkbox.

  4. Click Done.

Copy the token now — it will never be shown again. ContextQA doesn't store the value in a readable form, so support can't recover it. If you lose the value, delete the token and create a new one.

Use a token

Send the token as a bearer token in the Authorization header of each API request:

Calls that fall outside the token's scopes — or outside its IP allowlist, if you set one — are rejected.

An API token authenticates a request but does not establish an endpoint contract. For CI/CD automation, use only endpoint paths and payloads published in your workspace or an official ContextQA API reference. Do not infer paths from browser network traffic or reuse older username-and-password examples.

REST API contract availability

ContextQA does not currently publish a canonical public OpenAPI or Swagger URL for its control API on learning.contextqa.com. Use the exact routes displayed beneath the token scopes and any contract supplied to your workspace by ContextQA. For payload schemas, pagination, supported operations, or routes not shown in the scope list, contact your ContextQA administrator or support representative before building the integration.

Importing your application's OpenAPI/Swagger file into ContextQA API testing generates tests for the application under test; it is not the API contract for controlling ContextQA itself. The MCP tool reference is a separate, AI-assistant interface and should not be used as a substitute REST specification.

Permission scopes

Each scope maps to a fixed set of API routes. Select only the scopes your integration calls.

Scope
Routes

View Test Cases

GET /test_cases · GET /test_cases/{test_case_id}

Create & Edit Test Cases

POST /test_cases · PUT /test_cases/{test_case_id}

View Test Case Results

GET /test_case_results · GET /test_case_results/{test_case_result_id}

View Test Plans

GET /test_plans · GET /test_plans/{test_plan_id}

Create & Edit Test Plans

POST /test_plans · PUT /test_plans/{test_plan_id}

View Test Plan Results

GET /test_plan_results · GET /test_plan_results/{test_plan_result_id}

View Test Suites

GET /test_suites · GET /test_suites/{test_suite_id}

Create & Edit Test Suites

POST /test_suites · PUT /test_suites/{test_suite_id}

View Test Suite Results

GET /test_suite_results · GET /test_suite_results/{test_suite_result_id}

View Test Steps

GET /test_steps · GET /test_steps/{test_step_id}

Create & Edit Test Steps

POST /test_steps · PUT /test_steps/{test_step_id}

View Test Step Results

GET /test_step_results · GET /test_step_results/{test_step_result_id}

Send Email

POST /api/email/send — high abuse risk

View System Audit

GET /api/v1/system-audits

Full Access

Every scope above except Send Email

Full Access covers every scope except Send Email. Send Email is never implied by Full Access and you must grant it separately. Grant it only when the integration genuinely sends email.

Expiry options

Select an expiry when you create the token:

Option
Notes

7 days

30 days

Default

60 days

90 days

180 days

Maximum

Never expire

Not recommended

The server rejects any expiry beyond 180 days from creation unless Never expire is selected.

A token that never expires stays valid indefinitely and never needs renewal — which also means it never stops working if it leaks. Use Never expire only when rotation genuinely isn't possible.

Restrict a token to specific IPs

By default a token is Unrestricted and accepts calls from any IP address. To limit where it can be used:

  1. In the IP allowlist section, select Restrict to an allowlist.

  2. Enter an exact IPv4 address (for example, 203.0.113.10) or IPv6 address (for example, 2001:db8::1).

  3. Click Add IP address to add more addresses.

  4. Save the token.

Calls from any address not on the list are rejected before authentication.

Only exact IPv4 or IPv6 addresses are supported. CIDR ranges, hostnames, and zone identifiers are not accepted. Saving replaces the entire allowlist, so include every address the integration calls from.

Edit a token

You can change a token's permissions and IP allowlist after creation. The name and expiry are fixed.

  1. Go to Settings → API Tokens.

  2. Find the token, open its actions menu, and select Edit permissions.

  3. Update the scopes or IP allowlist.

  4. Click Save changes.

Permission changes take effect on the token's next request. The IP allowlist is replaced in full.

Deactivate, activate, or delete a token

From the actions menu next to each token:

  • Deactivate token — turns off an active token without deleting it. Calls made with it are rejected until you reactivate it.

  • Activate token — re-enables a deactivated token.

  • Delete token — permanently removes the token. This can't be undone.

Deleting a token is permanent. Any integration still using it stops working immediately. If you only need to pause access, deactivate the token instead.

Find a token

The API Tokens table supports searching and filtering:

  • Search by name — type in the search bar to filter by token name.

  • Status — filter by All statuses, Active, Deactivated, or Expired.

Rate limits

API tokens are subject to rate limits:

  • 120 requests per minute across the API.

  • 10 emails per hour for the Send Email scope.

Security best practices

  • Give each integration its own token so you can revoke one without affecting others.

  • Grant the narrowest set of scopes that works, and avoid Full Access unless the integration truly needs it.

  • Set the shortest practical expiry and rotate tokens before they lapse.

  • Restrict tokens to a known IP allowlist wherever the caller's addresses are stable.

  • Store token values in an approved secret manager — never in source control or shared configuration.

  • Delete or deactivate a token immediately if it may be exposed.

Frequently asked questions

Can an API token be restricted to an IPv6 address?

Yes. Select Restrict to an allowlist and enter an exact IPv6 address such as 2001:db8::1. ContextQA also accepts exact IPv4 addresses, but not CIDR ranges or hostnames.

How do I know which endpoints a scope grants?

The create and edit forms list the exact collection and item routes beneath each scope. Match those routes to the calls your integration makes, then select the narrowest set that covers them.

Related pages

PreviousSSO & Authentication
NextLicense Status and Expiry

Last updated

Was this helpful?