/tokens Endpoint

The /tokens endpoint tells you whether an API key works and returns the account it belongs to: its credit balance, the API key itself, and the active subscription. It does not analyse any image and does not use any credit, so you can call it to check a key before sending images, or to show the remaining credits in your application.

The WordPress plugin calls this endpoint when you save your API key, to check it, and on its Dashboard tab, to show your remaining credits.

Request

Endpoint

GET https://forvoyez.com/api/tokens

Headers

• Authorization (required): your API key, prefixed with Bearer , as for /describe.

The request has no body and no parameters.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://forvoyez.com/api/tokens

Response

Success Response

If the API key is valid, the API returns 200 OK and a JSON object with four fields: subscription, token, user, and success.

{
	"subscription": {
		"isSubscribed": true,
		"plan": {
			"description": "<p>Perfect for small projects, freelancers, and personal use.</p>",
			"name": "Starter"
		},
		"statusFormatted": "Active",
		"renewsAt": "2026-11-08T09:30:00.000000Z",
		"status": "active",
		"endsAt": null
	},
	"token": {
		"createdAt": "2026-10-01T09:30:00.000Z",
		"expiredAt": "2027-10-01T09:30:00.000Z",
		"name": "My WordPress site"
	},
	"user": {
		"registeredAt": "2024-06-12T08:15:00.000Z",
		"credits": 1234,
		"id": "user_2abcdefghijklmnopqrstuvwxyz",
		"email": "Not available",
		"name": "My WordPress site"
	},
	"success": true
}

• success: always true in a 200 response.
• user: the account the API key belongs to.
  • credits: the current credit balance (a number). This is the value to read to know how many images you can still analyse.
  • id: the account ID.
  • registeredAt: the date the account was created (ISO 8601).
  • name: the name of the API key, or User when the key has no name.
  • email: always Not available; the email address of the account is not returned.
• token: the API key used for the request.
  • name: the name you gave the key when you created it (null if it has none).
  • createdAt and expiredAt: the creation date and the expiration date of the key (ISO 8601). After expiredAt, the key is rejected with 401.
• subscription: the active subscription of the account.
  • isSubscribed: true when the account has an active subscription, false otherwise. When it is false, subscription has no other field.
  • plan: the name of the plan and its description (an HTML string).
  • status and statusFormatted: the status of the subscription, for example active and Active.
  • renewsAt and endsAt: the renewal date and the end date of the subscription as last received from the payment provider (ISO 8601 strings, or null).

The subscription details are informational: credits are added to your balance at each payment and never expire (see Limits and Quotas), so rely on user.credits rather than on the subscription dates.

Error Responses

If the request fails, the API returns the HTTP status code of the error and a JSON body (Content-Type: application/json) whose error field contains a human-readable message. The messages of this endpoint are not the same as those of /describe:

• 400 Bad Request

  • Malformed token: missing userId: the key is signed by ForVoyez but was not created from the dashboard. Create a new API key.
    • Body: {"error": "Malformed token: missing userId"}

• 401 Unauthorized

  • Missing or invalid authentication token: the Authorization header is missing, or it does not start with Bearer .
    • Body: {"error": "Missing or invalid authentication token"}
  • Invalid or expired token: the value is not a ForVoyez API key (for example a truncated copy), or the key has passed its expiration date.
    • Body: {"error": "Invalid or expired token"}
  • Unauthorized, invalid token: the key has been deleted from the dashboard (deleting a key revokes it immediately).
    • Body: {"error": "Unauthorized, invalid token"}

• 404 Not Found

  • User not found: the key is valid but the account it belongs to no longer exists.
    • Body: {"error": "User not found"}

• 500 Internal Server Error

  • Server error: an unexpected error occurred on the server side. Retry the request after a short wait.
    • Body: {"error": "Server error"}

An empty credit balance is not an error for this endpoint: it returns 200 OK with "credits": 0.

See Error Codes for the errors of every endpoint.