> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowpayroll.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an API token > Issues a new client credential for your account. The response carries `clientSecret` exactly once — store it before doing anything else. Retrying with the same `Idempotency-Key` answers 200 with the token already made and no secret; if the secret has been lost, rotate the token. State what the token reaches as either `organisationIds` or `allOrganisations: true`, never both. `allOrganisations` grants account-wide access — every organisation the account owns, including ones added later — and only somebody who already holds account-wide access may grant it (403 `whole_customer_access_denied` otherwise). `name` is 3 to 100 characters and unique within your account. An account may hold 5 API tokens, counting every client credential it holds and not only the ones created here. Being over the limit revokes nothing; it only refuses a new one. Three things answer 409, told apart by `message.token`: - `token_limit_reached` — the account already holds 5 tokens. Revoke one that is no longer used, or contact support to raise the allowance. - `duplicate_token_name` — another token in your account has that name. - `idempotency_key_reused` — that `Idempotency-Key` was already used for a different request body. 403 `billing_not_set_up` when billing is not set up for the account yet — email hello@flowpayroll.ai to agree pricing and set it up. Accounts onboarded by Flow Payroll are already set up. ## OpenAPI ````yaml /api-reference/specs/administration.json post /api-tokens openapi: 3.0.1 info: title: Administration API description: >- Manage your Flow Payroll account: the organisations it owns, the people who can sign in to it, the API tokens it holds, its brand, and a feed of recent administration activity. Every resource is scoped to the account your credentials belong to, so no request ever names a customer and the `X-Org-Id` header is not used. version: v1 servers: - url: https://api.sandbox.flowpayroll.ai/v1/administration security: - X-Auth-Token: [] tags: - name: Customer description: >- Your account: the customer every other resource on this API belongs to. Read it and rename it. - name: Organisations description: >- The organisations your account owns: list them with headcounts and your access to each, get one in full, and add one or several at a time. - name: Users description: >- The people who can sign in to your account: list, invite (one or many), resend invitations, and manage each person's direct grants and account-wide access. - name: API tokens description: >- The client credentials your integrations authenticate with: create (the secret is shown once), rename, rotate, revoke, and manage which organisations each token reaches. - name: Activity description: Recent administration actions in your account, newest first. paths: /api-tokens: post: tags: - API tokens summary: Create an API token description: >- Issues a new client credential for your account. The response carries `clientSecret` exactly once — store it before doing anything else. Retrying with the same `Idempotency-Key` answers 200 with the token already made and no secret; if the secret has been lost, rotate the token. State what the token reaches as either `organisationIds` or `allOrganisations: true`, never both. `allOrganisations` grants account-wide access — every organisation the account owns, including ones added later — and only somebody who already holds account-wide access may grant it (403 `whole_customer_access_denied` otherwise). `name` is 3 to 100 characters and unique within your account. An account may hold 5 API tokens, counting every client credential it holds and not only the ones created here. Being over the limit revokes nothing; it only refuses a new one. Three things answer 409, told apart by `message.token`: - `token_limit_reached` — the account already holds 5 tokens. Revoke one that is no longer used, or contact support to raise the allowance. - `duplicate_token_name` — another token in your account has that name. - `idempotency_key_reused` — that `Idempotency-Key` was already used for a different request body. 403 `billing_not_set_up` when billing is not set up for the account yet — email hello@flowpayroll.ai to agree pricing and set it up. Accounts onboarded by Flow Payroll are already set up. operationId: IssueApiToken parameters: - name: Idempotency-Key in: header description: >- Your own key for this create, so a retry after a lost response finds what the first attempt made instead of making a second one. Any unique string up to 255 characters; a UUID is the usual choice. Send the same value on every retry of the same request, and a new value for a new one — reusing a key for a different body answers 409 `idempotency_key_reused`. Keys are remembered for 24 hours. Optional, and a request without one simply has no replay protection. schema: maxLength: 255 type: string example: 8b1f4c1e-0000-4000-8000-000000000000 requestBody: content: application/json: schema: $ref: '#/components/schemas/IssueApiTokenRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiTokenIssuedResponseResponseBody' '201': description: Created content: application/json: schema: $ref: '#/components/schemas/ApiTokenIssuedResponseResponseBody' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' components: schemas: IssueApiTokenRequest: type: object properties: name: type: string description: Required. A display name, unique within your account. nullable: true organisationIds: type: array items: type: string description: >- The organisations the token reaches. State exactly one of this and `allOrganisations`. nullable: true allOrganisations: type: boolean description: >- Give the credential access to every organisation the account owns, including ones added later, instead of the ones named in `organisationIds`. State exactly one of the two. This is the widest grant this API makes, so only somebody who already holds account-wide access may ask for it. additionalProperties: false description: Issues a new API token (client credential) for your account. ApiTokenIssuedResponseResponseBody: type: object properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' content: $ref: '#/components/schemas/ApiTokenIssuedResponseContentResponse' validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' nullable: true additionalProperties: false ObjectResponseBody: type: object properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' content: $ref: '#/components/schemas/ObjectContentResponse' validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' nullable: true additionalProperties: false MessageWithTokenResponse: type: object properties: text: type: string token: type: string tokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true additionalProperties: false ApiTokenIssuedResponseContentResponse: type: object properties: data: $ref: '#/components/schemas/ApiTokenIssuedResponse' metadata: $ref: '#/components/schemas/ContentMetadataResponse' additionalProperties: false ValidationIssue: type: object properties: field: type: string reason: type: string reasonToken: type: string reasonTokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true additionalProperties: false ObjectContentResponse: type: object properties: data: nullable: true metadata: $ref: '#/components/schemas/ContentMetadataResponse' additionalProperties: false ValidationIssueArgument: type: object properties: name: type: string value: nullable: true additionalProperties: false ApiTokenIssuedResponse: type: object properties: clientId: type: string description: >- The credential's client id. Stable for the life of the token, across rotations. name: type: string description: The display name. clientSecret: type: string description: >- Shown once and stored nowhere. Null when the request replayed an earlier create, whose secret was returned to the first attempt. If it is lost, rotate the token. nullable: true organisationIds: type: array items: type: string description: The organisations the token reaches through direct grants. coversWholeCustomer: type: boolean description: >- Whether it holds account-wide access, which reaches every organisation the account owns, including ones added later. When true, `organisationIds` is not the whole picture and is usually empty. alreadyExisted: type: boolean description: >- True when this `Idempotency-Key` had already been fulfilled and nothing was created now. additionalProperties: false description: >- A newly created or rotated API token. The only response on this API that carries a secret. ContentMetadataResponse: type: object properties: dateFormat: type: string dateTimeFormat: type: string paginationToken: type: string nullable: true additionalProperties: false securitySchemes: X-Auth-Token: type: apiKey description: FlowPayroll JWT (raw token, no Bearer prefix) name: X-Auth-Token in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.