Skip to main content

Troubleshooting

This section covers common issues you may encounter when using the MindKey Connector API and how to resolve them.

Authentication Issues​

401 Unauthorized with API Key​

Possible causes:

  • Expired API key. API keys are valid for 365 days. Generate a new key in the Connector Access Control panel and update your integration. See Key Rotation.
  • Incorrect authorization scheme. Ensure you are using ApiKey-v2 (not ApiKey-v1) in the Authorization header: 
    Authorization: ApiKey-v2 YOUR_API_KEY
  • Revoked API key. Check the Connector Access Control panel to verify the key is still active.

401 Unauthorized with Microsoft Entra ID​

Possible causes:

  • Expired access token. Entra ID access tokens have a limited lifetime. Request a new token from your identity provider.
  • Unregistered tenant. Your Entra ID tenant must be registered in the Connector Access Control panel before any users or service principals can authenticate.
  • User not granted access. The specific user or service principal must be explicitly added in the Connector Access Control panel with the appropriate scopes.

404 when accessing an endpoint that should exist​

The API returns 404 Not Found instead of 403 Forbidden when you lack the required scope. Verify that your API key or Entra ID account has the correct scopes assigned for the endpoint you are trying to access.

User account works in MindKey UI but not in the Connector API​

When using Microsoft Entra ID with a user account (not a service principal), the user must have an active employee record with at least one active position in MindKey. Service principals do not have this requirement. See User Accounts vs. Service Principals.

Query Issues​

400 Bad Request on a query​

The response body contains a message describing the problem. Common causes:

  • Invalid property name. Check the property name against the API reference for the entity. Property names are case-sensitive.
  • Malformed filter expression. Ensure $filter expressions follow OData syntax: property operator value (e.g., $filter=active eq true).
  • Unsupported operation. Not all OData operations are supported on all properties. Simplify your query and add complexity incrementally to isolate the issue.

Results are truncated / not all records returned​

The API returns a maximum of 3,000 records per request. If more records match your query, the response includes an @odata.nextLink property. Follow this URL to retrieve the next page of results. See Pagination.

Using /$count in the URL returns 404​

The /$count route segment is not supported. Use the $count=true query parameter instead:

GET https://connector.mindkey.com/odata/v2/Employee?$count=true

The total count will appear in the @odata.count property of the response. See Using $count.

Parenthesis-style URLs return 404​

The API uses key-as-segment URL format. Use /Employee/EMP001 instead of /Employee('EMP001'). See URL Format.

Date filtering returns unexpected results​

Ensure dates are in YYYY-MM-DD format without quotes:

$filter=hireDate ge 2024-01-01

Do not wrap dates in single quotes. See Filtering by Date.

Integration Issues​

Power BI / Excel cannot connect​

  • Ensure you are using Microsoft Entra ID authentication (not API Key) for Microsoft 365 integrations.
  • Verify that your Entra ID tenant is registered and the user has been granted access with the required scopes.
  • Check that popup blockers are disabled during the Entra ID consent flow.

Data appears stale​

API responses reflect the current state of the MindKey database at query time. If data appears outdated, verify that the source data has been updated in MindKey itself.

Limits​

LimitValue
Maximum records per response3,000
API key expiration365 days
Last-used tracking update interval~5 minutes

Health Check​

To verify that the Connector API is reachable and operational, use the ping endpoint:

GET https://connector.mindkey.com/api/ping

This endpoint requires no authentication and returns pong if the service is running.