generated: '2026-07-31'
method: derived
source: openapi/nextiva-authentication-openapi.yml, openapi/nextiva-provider-authentication-openapi.yml,
  openapi/nextiva-sms-messaging-openapi.yml, openapi/nextiva-workitem-service-openapi.yml
docs: https://developer.nextiva.com/nextiva/docs/authentication
docs_note: >-
  The developer portal's Authentication page is an unfilled ReadMe placeholder
  ("Set up the welcome page for your API to help users make their first call")
  as of 2026-07-31, so the auth model below is derived from the published
  OpenAPI security schemes and the SDK architecture guide rather than from a
  written auth guide.
summary:
  types: [http]
  http_schemes: [basic, bearer]
  bearer_formats: [JWT]
  api_key_in: []
  oauth2_flows: []
  openid_connect: false
  mutual_tls: false
model: >-
  Two-step. HTTP basic credentials are exchanged for a JWT that carries the
  user's authorities; that JWT is then sent as an Authorization bearer token on
  every other operation and refreshed before expiry. There is no OAuth 2.0, no
  OpenID Connect, no API-key scheme and no mTLS anywhere in the published
  contracts, so there is also no scope surface (scopes/ is intentionally absent).
flow:
- step: 1
  operation: generateTokenWithAuthorities
  path: GET https://api.nextiva.com/provider/token-with-authorities
  auth: basicAuth
  returns: TokenResponse (JWT + user authorities)
- step: 2
  operation: '*'
  header: 'Authorization: Bearer <jwt>'
  auth: bearerAuth
- step: 3
  operation: refreshToken
  path: GET https://api.nextiva.com/provider/api/token-refresh
  auth: bearerAuth
  returns: RefreshTokenResponse
  note: A 401 here means the token is already expired — restart at step 1.
schemes:
- name: basicAuth
  type: http
  scheme: basic
  description: Basic authentication using username and password.
  sources:
  - openapi/nextiva-authentication-openapi.yml
- name: bearerAuth
  type: http
  scheme: bearer
  bearerFormat: JWT
  description: Bearer token authentication (JWT).
  sources:
  - openapi/nextiva-authentication-openapi.yml
  - openapi/nextiva-sms-messaging-openapi.yml
  - openapi/nextiva-workitem-service-openapi.yml
- name: springAuth
  type: http
  scheme: bearer
  bearerFormat: JWT
  description: >-
    Spring Security authentication using JWT tokens. All endpoints require an
    authenticated user context.
  sources:
  - openapi/nextiva-provider-authentication-openapi.yml
authorization:
  model: authorities
  detail: >-
    The token embeds the user's "authorities" — the Provider Token Service
    documents generating JWTs with various permission levels, plus time-limited
    portal access tokens and multi-tenant location-based tokens. A 403 "Access
    denied" is returned when the authenticated user lacks the authority for the
    requested token scope. No authority/permission catalog is published.
sdk_handling: >-
  Per the SDK architecture guide, the SDKs post credentials to the Provider
  Service, receive the token plus a payload describing where to route future
  requests, and attach the token to the HTTP header automatically on every
  subsequent call.
gaps:
- developer portal authentication page is an empty ReadMe placeholder
- no published authority/permission reference
- no token lifetime documented
- no OAuth 2.0 or OpenID Connect