Rocket Lawyer Servicetoken API

openapi: 3.2.0
info:
  title: Authentication Servicetoken API
  version: 1.0.0
  description: This API documentation describes the authentication mechanisms that enable access to the Rocket Lawyer’s APIs.
  termsOfService: https://rocketlawyer-public-us.apigee.io/terms
servers:
- url: https://api-sandbox.rocketlawyer.com/partners/v1/auth
  description: Sandbox
- url: https://api.rocketlawyer.com/partners/v1/auth
  description: Production
tags:
- name: Servicetoken
paths:
  /servicetoken:
    post:
      summary: Service Token Creation
      security:
      - BearerTokenAuth: []
      description: Request the creation of a Service Token by posting one purpose with a related claim claim parameter. In order for the Client Application to be allowed to request Service Tokens, its associated RL Api Client must have been created with at least one of the recognized RL backend System Roles.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceTokenRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceTokenResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                description: 'Fault string is one of the following:

                  - Access Token expired with code `keymanagement.service.access_token_expired`

                  - Invalid Access Token with code `keymanagement.service.invalid_access_token`

                  '
                example:
                  fault:
                    faultstring: Access Token expired
                    detail:
                      errorcode: keymanagement.service.access_token_expired
        '400':
          description: 'Bad Request. Possible reasons are:

            - Invalid purpose

            - Expiration Time is in the past

            - Mandatory claim missing for purpose

            - Claim not valid for purpose

            '
          content:
            application/json:
              schema:
                type: object
                description: Used for invalid combinations of purpose and properties
                example:
                  message: Request is missing mandatory fields or contains non-acceptable fields for purpose or purpose is invalid
                  error: BAD_REQUEST
                  status: 400
                  timestamp: '2021-10-13T15:56:40.980+00:00'
        '403':
          description: 'Forbidden. Possible reasons are:

            - None of the system roles are authorized to request Service Tokens

            - RL Header not allowed

            - Claim not allowed for purpose

            '
          content:
            application/json:
              schema:
                type: object
                description: Used for invalid combinations of purpose and properties
                example:
                  timestamp: 2022-03-18 18:28:40.239000+00:00
                  status: 403
                  error: FORBIDDEN
                  message: none of the system roles are authorized to request Service Tokens
                  path: /partners/v1/auth/servicetoken
      tags:
      - Servicetoken
      operationId: postServicetoken
      x-operation-id-source: derived
components:
  schemas:
    ServiceTokenResponse:
      required:
      - purpose
      - expirationTime
      - token
      properties:
        purpose:
          type: string
          title: Purpose
          description: echoes request value
          example: api.rocketlawyer.com/binder-party-access
        expirationTime:
          type: integer
          title: Expiration Time
          description: echoes request value
          example: 1607803932
        token:
          type: string
          format: jwt
          title: Service Token
          description: "Service Token in JWT format\n#### JWT decoded payload\nService Data `srv` contains:\n- Custom properties that were present in request\n- System values automatically added by service (e.g. brand and partner)\n```\n{\n  \"iss\": \"rocketlawyer.com\",\n  \"aud\": \"rocketlawyer.com/service-tokens\",\n  \"exp\": 1671776542,\n  \"iat\": 1633971684,\n  \"srv\": {\n    \"originalTenantId\": \"6bbddc2c-9c7c-4ead-9ca9-bda4fd78acc5\",\n    \"expirationTime\": 1671776542,\n    \"upid\": \"d790696c-a0d8-4ba2-ad65-0092e89904ac\",\n    \"partnerId\": \"0d790f9d-7ff9-4bc2-8577-255eaf4594c0\",                \n    \"originalClientId\": \"7fb9c003-b777-40c6-ade0-ac945c9d710b\",\n    \"purpose\": \"api.rocketlawyer.com/demo/things\",\n    \"brandId\": \"5ded0acb-2cd2-405f-9568-996e480ff466\",\n  }\n}\n```\n"
          example: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJyb2NrZXRsYXd5ZXIuY29tIiwiYXVkIjoicm9ja2V0bGF3eWVyLmNvbS9zZXJ2aWNlLXRva2VucyIsImV4cCI6MTY3MTc3NjU0MiwiaWF0IjoxNjMzOTcxNjg0LCJzcnYiOnsib3JpZ2luYWxUZW5hbnRJZCI6IjZiYmRkYzJjLTljN2MtNGVhZC05Y2E5LWJkYTRmZDc4YWNjNSIsImV4cGlyYXRpb25UaW1lIjoxNjcxNzc2NTQyLCJwYXJ0bmVySWQiOiIwZDc5MGY5ZC03ZmY5LTRiYzItODU3Ny0yNTVlYWY0NTk0YzAiLCJvcmlnaW5hbENsaWVudElkIjoiN2ZiOWMwMDMtYjc3Ny00MGM2LWFkZTAtYWM5NDVjOWQ3MTBiIiwicHVycG9zZSI6ImFwaS5yb2NrZXRsYXd5ZXIuY29tL2RlbW8vdGhpbmdzIiwiYnJhbmRJZCI6IjVkZWQwYWNiLTJjZDItNDA1Zi05NTY4LTk5NmU0ODBmZjQ2NiIsIm93bmVyIjoidXNlcjEifX0.<content redacted> '
    ServiceTokenRequest:
      required:
      - purpose
      - expirationTime
      properties:
        purpose:
          type: string
          title: Purpose
          example: api.rocketlawyer.com/binder-party-access
          description: "Defines the how the the Service Token will be used to restrict access. This can be either by unique party identifier (UPID) or by Interview ID. Only registered purposes are allowed and property parameter must correspond to purpose. \n### To restrict by UPID use \"api.rocketlawyer.com/binder-party-access\"\n### To restrict by Interview Id use \"api.rocketlawyer.com/rocketdoc\""
        expirationTime:
          type: integer
          title: Expiration Time
          example: 1671776542
          description: Expressed as a number of seconds elapsed since the Epoch. Cannot denote a value in the past (with regards to when request hits the application endpoint).
        upid:
          type: string
          title: Purpose dependent claim
          description: upid is an example associated with Binder Party Access Purpose.
          example: d790696c-a0d8-4ba2-ad65-0092e89904ac
      additionalProperties:
        type: string
        title: Purpose dependent properties
        description: "Custom properties that depend on the purpose. For instance, where restricting by party then Universal Party Identifier `upid` is required, where restricting by interview (rocketdoc purpose) then `interviewId` is required. Request is deemed invalid (400) if request does not contain the required fields for the purpose. \n### Binders\n```\n{\n  \"purpose\" : \"api.rocketlawyer.com/binder-party-access\",\n  \"expirationTime\" : 1671776542,\n  \"upid\" : \"d25eb612-17c2-4e58-9700-28bfa25e0df0\"\n}\n```\n"
  securitySchemes:
    BearerTokenAuth:
      type: http
      scheme: bearer