Troubleshoot API access issues

Use this guide when the vScope API is unreachable, returns authorization errors, or Swagger/OpenAPI docs load inconsistently.

Typical symptoms

• You can open /apidoc, but API requests fail.
• You receive 401 Unauthorized or 403 Forbidden from API endpoints.
• The API documentation UI loads, but schema/content requests are rejected.
• The browser shows certificate warnings (for example, “Not secure”) and API calls fail.
• API calls fail only through a reverse proxy or only on one URL/path.

Step 1: Confirm session and token

1. Sign in to vScope again in your browser.
2. If you use API tokens, generate a fresh token and test again.
3. Verify you send the token in the expected header format:

token: <your-token>

If your session has expired or the token is invalid, requests commonly return 401.

For token usage basics, see API Basics and Exporting data via API.

Step 2: Verify user permissions

API access always inherits the linked user permissions. A valid token can still fail with 403 if the user is missing rights.

1. Confirm which user the token belongs to.
2. Verify that user can access the same data in the vScope UI.
3. Review group and permission configuration.

If this is a role/permission issue, requests typically return 403.

Related reference: Groups and permissions.

Step 3: Validate URL and path routing

Check that your requests hit the expected base URL and path.

1. Test direct access to your vScope server URL.
2. Test the same endpoint through any reverse proxy/load balancer.
3. Confirm paths are not rewritten incorrectly (for example /apidoc/openapi.json routed to the wrong backend path).

A common failure is that /apidoc (UI) is reachable, but schema or API paths are blocked or rewritten.

Step 4: Check reverse proxy and TLS/HTTPS setup

If API access differs between direct and proxied URLs, review your proxy/TLS configuration.

1. Confirm TLS certificates are valid and trusted by clients.
2. Ensure the proxy forwards required headers and does not strip auth headers.
3. Verify protocol/port forwarding (HTTP vs HTTPS) is consistent end-to-end.
4. Confirm no security policy blocks schema/API routes while allowing static UI assets.

Certificate or TLS issues can cause browser warnings and failed API calls even when pages appear to load.

Step 5: Compare response codes and logs

Use HTTP status codes to narrow the root cause quickly:

• 401: authentication/session/token problem.
• 403: permission/authorization problem.
• 404: wrong URL/path rewrite/routing issue.
• 5xx: backend or proxy/service failure.

When to contact support

Contact support if you have:

• Verified token/session and permissions.
• Confirmed URL/path and proxy/TLS settings.
• Captured failing endpoint, timestamp, and HTTP status code.

Include those details in your case to speed up troubleshooting.

Contact support