Nextiva Provider Token Service API

openapi: 3.0.3
info:
  title: Provider Authentication API
  version: 1.0.0
  description: '## Overview

    The Provider Authentication API manages secure token generation and authentication for provider services. It provides
    endpoints for generating JWT tokens with various permission levels, authenticating users, and managing portal access tokens.


    ## Key Features

    - Generate JWT tokens with user authorities for secure API access

    - Authenticate users and redirect with secure tokens

    - Generate time-limited portal access tokens

    - Support for multi-tenant location-based token generation


    ## Security

    All endpoints require authenticated user context via Spring Security. The API uses JWT tokens for stateless authentication
    and includes tenant-based location routing for multi-tenant deployments.

    '
  contact:
    name: API Support
    email: api-support@nextiva.com
  license:
    name: Proprietary
    url: https://www.nextiva.com
servers:
- url: https://api.nextiva.com/provider
  description: Production server
- url: https://api-staging.nextiva.com/provider
  description: Staging server
- url: http://localhost:8080
  description: Development server
tags:
- name: Authentication
  description: Token generation and authentication operations
paths:
  /token-with-authorities:
    get:
      tags:
      - Authentication
      summary: Generate token with user authorities (test)
      description: 'Generates a JWT token containing the authenticated user''s authorities and tenant location information.

        This endpoint provides comprehensive token generation with full permission context.

        '
      operationId: generateTokenWithAuthorities
      security:
      - springAuth: []
      x-readme:
        code-samples:
        - language: shell
          name: cURL
          code: 'curl -X GET "https://api.nextiva.com/provider/token-with-authorities"                 -H "Authorization:
            Bearer {existing-token}"

            '
        - language: node
          name: JavaScript (fetch)
          code: "const response = await fetch('https://api.nextiva.com/provider/token-with-authorities', {\n  headers: { 'Authorization':\
            \ 'Bearer ' + existingToken }\n});\nconst data = await response.json();\n"
        - language: java
          name: Java
          code: "HttpClient client = HttpClient.newHttpClient();\nHttpRequest request = HttpRequest.newBuilder()\n    .uri(URI.create(\"\
            https://api.nextiva.com/provider/token-with-authorities\"))\n    .header(\"Authorization\", \"Bearer \" + existingToken)\n\
            \    .build();\nHttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());\n"
      responses:
        '200':
          description: Successfully generated token with authorities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenAuthenticationResponse'
              examples:
                withClientLocation:
                  summary: Response with client location
                  value:
                    clientLocation: https://client1.nextiva.com
                    location: https://api1.nextiva.com
                    token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                withoutClientLocation:
                  summary: Response without client location
                  value:
                    clientLocation: null
                    location: https://api1.nextiva.com
                    token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /token:
    get:
      tags:
      - Authentication
      summary: Generate basic token
      description: 'Generates a basic JWT token without authorities, containing only essential user information and tenant
        location.

        Use this endpoint when full permission context is not required.

        '
      operationId: generateToken
      security:
      - springAuth: []
      x-readme:
        code-samples:
        - language: shell
          name: cURL
          code: 'curl -X GET "https://api.nextiva.com/provider/token"                 -H "Authorization: Bearer {existing-token}"

            '
        - language: node
          name: JavaScript (fetch)
          code: "const response = await fetch('https://api.nextiva.com/provider/token', {\n  headers: { 'Authorization': 'Bearer\
            \ ' + existingToken }\n});\nconst data = await response.json();\n"
        - language: java
          name: Java
          code: "HttpClient client = HttpClient.newHttpClient();\nHttpRequest request = HttpRequest.newBuilder()\n    .uri(URI.create(\"\
            https://api.nextiva.com/provider/token\"))\n    .header(\"Authorization\", \"Bearer \" + existingToken)\n    .build();\n\
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());\n"
      responses:
        '200':
          description: Successfully generated token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenAuthenticationResponse'
              examples:
                basicToken:
                  summary: Basic token response
                  value:
                    clientLocation: null
                    location: https://api1.nextiva.com
                    token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth:
    post:
      tags:
      - Authentication
      summary: Authenticate and redirect
      description: 'Authenticates the current user and performs a redirect to the tenant-specific users service login endpoint
        with a generated token.

        This endpoint is typically used for SSO flows and portal integrations.

        '
      operationId: authenticate
      security:
      - springAuth: []
      x-readme:
        code-samples:
        - language: shell
          name: cURL
          code: 'curl -X POST "https://api.nextiva.com/provider/auth"                 -H "Authorization: Bearer {existing-token}"                 -i

            '
        - language: node
          name: JavaScript (fetch)
          code: "const res = await fetch('https://api.nextiva.com/provider/auth', {\n  method: 'POST',\n  headers: { 'Authorization':\
            \ 'Bearer ' + existingToken },\n  redirect: 'manual'\n});\nconsole.log(res.status, res.headers.get('Location'));\n"
      responses:
        '302':
          description: Redirect to tenant location with token
          headers:
            Location:
              description: Redirect URL with token parameter
              schema:
                type: string
                example: https://api1.nextiva.com/users/api/login?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /portal/token-with-authorities:
    get:
      tags:
      - Authentication
      summary: Generate portal access token
      description: 'Generates a time-limited token specifically for portal access with a 3-hour expiration time.

        Includes audit logging for security tracking and returns expiration timestamp.

        '
      operationId: generatePortalToken
      security:
      - springAuth: []
      x-readme:
        code-samples:
        - language: shell
          name: cURL
          code: 'curl -X GET "https://api.nextiva.com/provider/portal/token-with-authorities"                 -H "Authorization:
            Bearer {existing-token}"

            '
        - language: node
          name: JavaScript (fetch)
          code: "const response = await fetch('https://api.nextiva.com/provider/portal/token-with-authorities', {\n  headers:\
            \ { 'Authorization': 'Bearer ' + existingToken }\n});\nconst data = await response.json();\n"
      responses:
        '200':
          description: Successfully generated portal token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              examples:
                portalToken:
                  summary: Portal token with expiration
                  value:
                    location: https://api1.nextiva.com
                    token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                    expiresAt: 1672531200000
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-implementation-notes: '- Token expires after 3 hours from issuance

        - Audit trace is logged for successful token generation

        - Returns null body for error responses

        '
components:
  schemas:
    TokenAuthenticationResponse:
      type: object
      description: Response containing JWT token and location information
      properties:
        clientLocation:
          type: string
          nullable: true
          description: Client-specific location URL for multi-tenant deployments
          example: https://client1.nextiva.com
        location:
          type: string
          description: API location URL for the tenant
          example: https://api1.nextiva.com
        token:
          type: string
          description: JWT token for authentication
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
      required:
      - token
      - location
    TokenResponse:
      type: object
      description: Extended response with token expiration information
      additionalProperties: true
      properties:
        location:
          type: string
          description: API location URL for the tenant
          example: https://api1.nextiva.com
        token:
          type: string
          description: JWT token for authentication
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
        expiresAt:
          type: integer
          format: int64
          description: Token expiration timestamp in milliseconds since epoch
          example: 1672531200000
      required:
      - location
      - token
      - expiresAt
    ErrorResponse:
      type: object
      description: Standardized error response
      properties:
        type:
          type: string
          description: Error type classification
          example: AUTHENTICATION_ERROR
        message:
          type: string
          description: Human-readable error message
          example: Invalid or expired authentication token
        code:
          type: string
          description: Internal error code
          example: AUTH_001
        param:
          type: string
          nullable: true
          description: Parameter that caused the error, if applicable
          example: Authorization
      required:
      - type
      - message
      - code
  securitySchemes:
    springAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Spring Security authentication using JWT tokens.

        All endpoints require an authenticated user context.

        '
security:
- springAuth: []
x-business-rules:
- Portal tokens have a fixed 3-hour expiration time
- Token generation includes tenant location resolution
- All token operations require authenticated user context
- Audit logging is performed for portal token generation
x-dependencies:
- TokenHandler service for JWT generation
- TenantLocationService for multi-tenant routing
- AuditTraceService for security logging
- Spring Security for authentication context
x-changelog:
- version: 1.0.0
  date: '2024-01-01'
  changes:
  - Initial API documentation
  - Four authentication endpoints documented