---
updatedAt: 2026-09-24T22:59:05.000Z
agentTools:
  projectIndex: https://developers.getbyrd.com/llms.txt
---

# Log in and get an access token

Exchanges your API key and secret, or your dashboard email and
password, for a JWT access token, valid for 7 days unless you ask
for less. Send the token as
`Authorization: Bearer <token>` on every other call. The endpoint
allows at most five calls per minute, so reuse the token until it
expires. See the Authentication guide.



# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "description": "The byrd APIs for managing products, inbound deliveries, shipments and returns.",
    "contact": {
      "email": "info@getbyrd.com",
      "name": "General company contact",
      "url": "https://getbyrd.com/kontakt/"
    },
    "license": {
      "name": "Copyright byrd technologies GmbH"
    },
    "termsOfService": "https://getbyrd.com/agb/",
    "version": "20260924",
    "title": "byrd APIs"
  },
  "servers": [
    {
      "description": "Production server",
      "url": "https://api.getbyrd.com/"
    }
  ],
  "security": [
    {
      "tokenAuth": []
    }
  ],
  "paths": {
    "/v2/login": {
      "post": {
        "operationId": "loginapiv2_post",
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "token",
                    "payload"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LoginResponse"
                    }
                  },
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/LoginResponse"
                    }
                  ]
                }
              }
            },
            "description": "The access token and its decoded payload, sent twice with the same values: at the top level, for older clients, and under `data`.\n"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        },
        "tags": [
          "Authentication"
        ],
        "description": "Exchanges your API key and secret, or your dashboard email and\npassword, for a JWT access token, valid for 7 days unless you ask\nfor less. Send the token as\n`Authorization: Bearer <token>` on every other call. The endpoint\nallows at most five calls per minute, so reuse the token until it\nexpires. See the Authentication guide.\n\n",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PostLogin"
              }
            }
          }
        },
        "security": [],
        "summary": "Log in and get an access token"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "tokenAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Authorization with previously obtained JSON Web Token"
      }
    },
    "responses": {
      "Error": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Generic error response"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message",
          "errors"
        ],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "Authentication.AuthenticationRequired",
              "Authentication.ExpiredJWTToken",
              "Authentication.InvalidCredentials",
              "Authentication.InvalidJWTToken",
              "Authentication.LocalityRequired",
              "Authentication.MissingPermission",
              "Authentication.ReadOnly",
              "Authentication.RoleNotAllowed",
              "Authentication.UserLocked",
              "Exception.404",
              "Exception.500",
              "Request.InvalidPagination",
              "Request.InvalidQuery",
              "Request.InvalidSchema",
              "Request.NoInput",
              "Request.ResourceNotFound"
            ]
          },
          "message": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "Embedded instance of Error"
            }
          }
        },
        "title": "Error"
      },
      "LoginPayload": {
        "type": "object",
        "properties": {
          "aud": {
            "type": "string",
            "description": "Audience the token is issued for: `api.getbyrd.com`."
          },
          "iss": {
            "type": "string",
            "description": "Issuer of the token: `api.getbyrd.com`."
          },
          "jti": {
            "type": "string",
            "description": "Unique ID of the token (UUID)."
          },
          "role": {
            "type": "string",
            "description": "Role of the user the token is issued to, e.g. `customer`."
          },
          "sub": {
            "type": "string",
            "description": "ID of the user the token is issued to (UUID)."
          },
          "loc": {
            "type": "array",
            "description": "IDs of the warehouses your account is linked to (UUIDs).",
            "items": {
              "type": "string"
            }
          },
          "fpk": {
            "type": "string",
            "description": "Key of the fulfillment provider your account belongs to."
          },
          "exp": {
            "type": "integer",
            "description": "When the token expires, as a Unix timestamp in seconds."
          },
          "iat": {
            "type": "integer",
            "description": "When the token was issued, as a Unix timestamp in seconds."
          },
          "nbf": {
            "type": "integer",
            "description": "Time before which the token is not accepted, as a Unix timestamp in seconds."
          },
          "scp": {
            "type": "array",
            "description": "Names of the permissions granted to the user.",
            "items": {
              "type": "string"
            }
          },
          "imp": {
            "type": "string",
            "description": "ID of the byrd user who opened this session on your behalf (UUID); absent for your own logins."
          },
          "ron": {
            "type": "boolean",
            "description": "Whether the session is read-only; absent for your own logins."
          },
          "authMethod": {
            "type": "string",
            "description": "How the credentials were checked when the session started.\n\n- `apikey`: API key and secret\n- `password`: login email and password\n- `sso`: single sign-on"
          }
        },
        "additionalProperties": false,
        "title": "Login payload"
      },
      "LoginResponse": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string",
            "readOnly": true,
            "description": "JWT access token. Send it as `Authorization: Bearer <token>` on every other call."
          },
          "payload": {
            "readOnly": true,
            "description": "Decoded claims of `token`.",
            "allOf": [
              {
                "$ref": "#/components/schemas/LoginPayload"
              }
            ]
          }
        },
        "additionalProperties": false,
        "title": "Login response"
      },
      "PostLogin": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string",
            "description": "Your API key. A value containing `@` is treated as the email address you log in to the dashboard with."
          },
          "password": {
            "type": "string",
            "description": "Your API secret, or the password of your login email when `username` is an email address."
          },
          "validity": {
            "type": "integer",
            "default": 604800,
            "description": "How long the token stays valid, in seconds. Defaults to and is capped at 604800 (7 days)."
          }
        },
        "required": [
          "password",
          "username"
        ],
        "title": "Post login"
      }
    }
  },
  "tags": [
    {
      "name": "Authentication",
      "description": "Log in with your API key to get an access token, refresh it, and read or update your account."
    }
  ],
  "x-readme": {
    "apply-tag-changes": true,
    "apply-endpoint-order": true
  }
}
```