# Authenticate with the API.

This endpoint is needed to generate your access token. Access to the API is by Bearer Access Tokens. These are valid for 15 minutes. You can have multiple Access Tokens active at the same time if needed. See the [Guide to Authentication](/docs/authentication) for full details.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Fire Financial Services Business API",
    "description": "The fire.com API allows you to deeply integrate Business Account features into your application or back-office systems.\n",
    "version": "1.0",
    "contact": {
      "name": "Fire API",
      "url": "https://docs.fire.com",
      "email": "api@fire.com"
    }
  },
  "servers": [
    {
      "url": "https://api.fire.com/business",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/v1/apps/accesstokens": {
      "post": {
        "summary": "Authenticate with the API.",
        "description": "This endpoint is needed to generate your access token. Access to the API is by Bearer Access Tokens. These are valid for 15 minutes. You can have multiple Access Tokens active at the same time if needed. See the [Guide to Authentication](/docs/authentication) for full details.",
        "tags": [
          "Authentication"
        ],
        "operationId": "authenticate",
        "security": [],
        "requestBody": {
          "required": true,
          "description": "Authentication data",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthenticationData"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Access token created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccessToken"
                }
              }
            }
          },
          "400": {
            "description": "An error has occured. Any 403 errors usually mean your access token is invalid or missing. For other errors, check the validity of your input, and if you are permitted to access this endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "title": "apiErrors",
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApiError"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "An error has occured. Any 403 errors usually mean your access token is invalid or missing. For other errors, check the validity of your input, and if you are permitted to access this endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "title": "apiErrors",
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApiError"
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "An error has occured. Any 403 errors usually mean your access token is invalid or missing. For other errors, check the validity of your input, and if you are permitted to access this endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "title": "apiErrors",
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApiError"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "webhook": {
      "post": {
        "summary": "Event Webhook",
        "tags": [
          "Webhooks"
        ],
        "description": "Webhooks allow you to be notified of events as they happen on your Fire accounts. The below sample response shows how a webhook from Fire will arrive at your server. See our 'Webhooks' guide for more detailed information.",
        "requestBody": {
          "required": true,
          "content": {
            "application/jwt": {
              "schema": {
                "type": "string",
                "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A 200 response is required from your server. Returns a 200 response to indicate that the data was received successfully."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Access Token"
      }
    },
    "schemas": {
      "AccessToken": {
        "title": "accessToken",
        "type": "object",
        "properties": {
          "businessId": {
            "type": "integer",
            "format": "int64",
            "description": "The business ID for the business.",
            "example": 248
          },
          "apiApplicationId": {
            "type": "integer",
            "format": "int64",
            "description": "The ID of the application you are using.",
            "example": 433
          },
          "expiry": {
            "type": "string",
            "format": "date-time",
            "description": "The expiry date and time for this token (ISO-8601).",
            "example": "2020-10-22T07:48:56.460Z"
          },
          "permissions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The permissions assigned to the Access Token as an array of strings. This provides information on what API access it is allowed. See the section on Scope below.",
            "example": [
              "PERM_BUSINESSES_GET_ACCOUNTS",
              "PERM_BUSINESSES_GET_ACCOUNT_TRANSACTIONS"
            ]
          },
          "accessToken": {
            "type": "string",
            "description": "The App Bearer Access Token you can use in further API calls.",
            "example": "4ADFB67A-0F5B-4A9A-9D74-34437250045C"
          }
        }
      },
      "ApiError": {
        "title": "apiError",
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "format": "int64",
            "description": "Error Code",
            "example": 50051
          },
          "message": {
            "type": "string",
            "description": "The error message",
            "example": "Sorry, we are unable to proceed with your request."
          }
        }
      },
      "AuthenticationData": {
        "title": "authentication",
        "type": "object",
        "properties": {
          "clientId": {
            "type": "string",
            "description": "The Client ID for this API Application",
            "example": "4ADFB67A-0F5B-4A9A-9D74-34437250045C"
          },
          "refreshToken": {
            "type": "string",
            "description": "The Refresh Token for this API Application",
            "example": "4ADFB67A-0F5B-4A9A-9D74-34437250045C"
          },
          "nonce": {
            "type": "integer",
            "format": "int64",
            "description": "A random non-repeating number used as a salt for the `clientSecret` below. The simplest nonce is a unix time.",
            "example": 728345638475
          },
          "grantType": {
            "type": "string",
            "enum": [
              "AccessToken"
            ],
            "description": "Always `AccessToken`. (This will change to `refresh_token` in a future release.)"
          },
          "clientSecret": {
            "type": "string",
            "description": "The SHA256 hash of the nonce above and the app’s Client Key. The Client Key will only be shown to you when you create the app, so don’t forget to save it somewhere safe. SECRET=( `/bin/echo -n $NONCE$CLIENT_KEY | sha256sum` ).",
            "example": "4ADFB67A-0F5B-4A9A-9D74-34437250045C"
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "Access to the API is by Bearer Access Tokens."
    },
    {
      "name": "Webhooks",
      "description": "Events you can receive in realtime"
    }
  ]
}
```