---
updatedAt: 2026-09-24T13:53:07.000Z
---

# Refresh Auth token

Refresh / renew expired auth tokens using `refresh token`
that was issued with the initial auth/login request.

Refresh token is the preferred way to re-authenticate/renew
an expired token due to superior performance when comparing
to the `acquire auth token` method.


# OpenAPI definition

```json
{
  "openapi": "3.0.2",
  "info": {
    "title": "Protect+ API",
    "version": "1.1",
    "termsOfService": "https://firstorion.com/terms-use/",
    "contact": {
      "name": "First Orion"
    },
    "description": "**Protect+** is a lightweight REST based API that can easily\nintegrate with a network element and provide feedback on a call-by-call basis.\n\nBy providing the calling number in the API POST request, the\nAPI response can provide the associated Risk Level,\nand Category.  Through the client’s own local policies,\nthis information in the API response can be leveraged to take\nactionable steps such as warning the called party of a scam\ncall or providing call purpose for a low-risk legitimate\nbusiness such as Charity, or even blocking the call outright.\n\nThe architecture of Protect+, and all of First Orion’s\nreal-time call protection services, allows for continuous\ndata and analytics updates. The continuous availability of\nnew data provided to the protection services also allows\nfor low latency, which is critical for any real-time\nprotection solution.\n\n### How to use the APIs\n\n#### Basic request flow\n\n1. Acquire an auth token by sending a `POST` request using the api key\nand api secret First Orion has provided to you.\n2. Use the token as an Authorization header as you submit\nrequests to various API endpoints.\n3. When the auth token expires you must acquire a new token\nusing the `refresh_token` received as part of step #1.\nThis is done by submitting a `POST` request to the\n`refresh` endpoint of the Auth service.\n"
  },
  "servers": [
    {
      "url": "https://api.firstorion.com",
      "description": "Production environment"
    },
    {
      "url": "https://api.forp-lab.com",
      "description": "Lab environment for customer integration"
    }
  ],
  "tags": [
    {
      "name": "Auth",
      "description": "Authentication endpoints for initial authentication\nand refreshing an expired token.\n\n### Time to live\n\nAuth Tokens expire automatically in 60 minutes.\nClient application must refresh an expired token in order\nsubmit further requests.\n\n### Refresh token\n\nIt is recommended that expired tokens are refreshed\nusing the `refresh_token`.\n"
    }
  ],
  "components": {
    "schemas": {
      "AuthResponse": {
        "type": "object",
        "example": {
          "token": "REDACTED",
          "refresh_token": "REDACTED",
          "expires_at": 1700068211,
          "expires_in": 3600,
          "token_type": "Bearer"
        },
        "properties": {
          "token": {
            "type": "string",
            "description": "Access token is a JWT for future authentication and authorization of First Orion APIs"
          },
          "refresh_token": {
            "type": "string",
            "description": "Refresh token is a JWT that can be used to refresh your access token when it is about to expire. See the Refresh Token API."
          },
          "expires_in": {
            "type": "integer",
            "description": "Number of seconds that this access token is valid for, from the time of generation",
            "example": 3600
          },
          "token_type": {
            "type": "string",
            "example": "Bearer"
          },
          "expires_at": {
            "type": "integer",
            "description": "Unix epoch timestamp when this access token will expire",
            "example": 1700068211
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request"
      },
      "AuthorizationFailed": {
        "description": "Login Failed."
      },
      "ResourceNotFound": {
        "description": "Resource not found."
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "paths": {
    "/v1/auth/refresh": {
      "post": {
        "summary": "Refresh Auth token",
        "description": "Refresh / renew expired auth tokens using `refresh token`\nthat was issued with the initial auth/login request.\n\nRefresh token is the preferred way to re-authenticate/renew\nan expired token due to superior performance when comparing\nto the `acquire auth token` method.\n",
        "operationId": "RefreshAuthToken",
        "tags": [
          "Auth"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/AuthorizationFailed"
          },
          "404": {
            "$ref": "#/components/responses/ResourceNotFound"
          }
        },
        "parameters": [
          {
            "name": "X-API-KEY",
            "in": "header",
            "description": "API key credential",
            "required": true,
            "schema": {
              "type": "string",
              "format": "password"
            }
          },
          {
            "name": "X-REFRESH-TOKEN",
            "in": "header",
            "description": "Refresh token acquired with last access token",
            "required": true,
            "schema": {
              "type": "string",
              "format": "password"
            }
          },
          {
            "name": "X-SERVICE",
            "in": "header",
            "description": "Required header for routing purposes",
            "required": true,
            "schema": {
              "type": "string",
              "default": "auth",
              "example": "auth"
            }
          }
        ]
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": true
  }
}
```