openapi: "3.0.3"
info:
  description: >
    The Synergy Sports APIs make use of JWT tokens to authorise requests.  Those tokens can be obtained by using the credentials provided on sign up in the following getToken call.

  version: "1.0.0"
  title: "Synergy Sports - Auth API"

tags:
- name: "Datacore"
  description: "These calls obtain tokens to access Datacore.
        <h3>Permission structure</h3>
        <p>
         Customers are give access to a number (1+) of applications.  Each application has a number of permissions over a number (0+) of organizations.  Each application is given a number (1+) of credentialId/credentialSecret pairs.  These credentials give access to that specific application.
        <p>
        Users/Persons can also be given access to an application, which allows them access without using the credentialId/credentialSecret pair.
        <p>
        There are two different methods of providing credentials:
        <ol>
        <li><b>Application Credentials</b>
        These credentials would be used to authenticate an application/service to the API where those credentials had been provided to the customer.<br>They use the fields `credentialId`/`credentialSecret`
        <li><b>Individual User Credentials</b><br>
        These credentials would be used to authenticate a user/person to the API.  These credentials would be obtained from the User Sign on (SSO) service.  They use the fields `userIdentityToken`/`applicationId`
        </ol>
        </p>"

- name: "Products"
  description: "Get tokens to access products (other than datacore)"
- name: "Users"
  description: "These API calls allow a logged in user to obtain information about which customers and products they have access to."
- name: "Token Information"
  description: "These API calls allow a logged in user to obtain information about their current token and what permissions/access they can request on subsequent tokens."

servers:
- url: "https://token.connect.sportradar.com/v1"
  description: "Production server"
- url: "https://token.stg.connect-nonprod.sportradar.dev/v1"
  description: "NonProduction/Staging server"

paths:
  /oauth2/rest/token:
    post:
      tags:
        - "Datacore"
      summary: "Get an Access Token for the Datacore REST API"
      description: "This call will return a JWT that you can use to make API calls to the DataCore REST API service. The JWT is generated in response to parameters and the exchange of identity credentials.
           "
      operationId: "getToken"
      x-hideTryItPanel: true
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Credentials'
                - $ref: '#/components/schemas/CredentialsUser'
              additionalProperties: false
              properties:
                sport:
                  $ref: '#/components/schemas/Sport'
                organization:
                  type: "object"
                  description: > 
                    This key controls which organization/s you wish to authenticate to.  There are two mutually exclusive options.
                     1. By `organizationId`
                    To do this you provide a list of `organizationsId`s that you want this token to provide access to.  You can provide up to a maxium of 5 organizations this way.  You must have previously been given permission to access these organizations. 
                     2. By `orgGroup`
                    If you have been given access to an organization group code, then you can use this here to gain access to all organizations in that group.
                    
                    You must chose one (and only one) of these options.
                  maxProperties: 1
                  minProperties: 1
                  additionalProperties: false
                  properties:
                    group:
                      description: "The organization group code that you want this token to access"
                      type: "string"
                      example: "FIBA"
                    id:
                      description: "A list of `organizationId`s (up to 5) that you want this token to access"
                      type: "array"
                      maxItems: 5
                      uniqueItems: true
                      items:
                        type: string
                        example: 'b1a23'
                      example: ['b1a23','b1y76']
                scopes:
                  description: "A list of permission scopes that you want for this token.  If not provided then all available permissions will be added. You would use this if you want your token to have less permissions that you are normally allowed. If you have different permissions for different organizations, then you will be given the common set of permissions over all the organizations you specified. If you request scopes that you do not have permission for, then call will fail."
                  type: "array"
                  uniqueItems: true
                  items:
                    type: string
                    example: 'read:organization'
                  example: ['read:organization','write:organization']
              required:
                - sport

      responses:
        200:
          $ref: '#/components/responses/TokenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /stream/fixture/access:
    post:
      tags:
        - "Datacore"
      summary: "Get access to the Datacore Streaming API for a Fixture"
      description: "This call will return information about how to access the the DataCore Streaming API service specific to a Fixture."
      operationId: "getStreamAuthFixture"
      x-hideTryItPanel: true
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Credentials'
                - $ref: '#/components/schemas/CredentialsUser'
              additionalProperties: false
              properties:
                fixtureId:
                    $ref: '#/components/schemas/FixtureId'
                sport:
                    $ref: '#/components/schemas/Sport'
                scopes:
                    $ref: '#/components/schemas/StreamScopes'
                includePort:
                    $ref: '#/components/schemas/IncludePort'
              required:
                - fixtureId
                - sport
                - scopes

      responses:
        200:
          $ref: '#/components/responses/StreamAuthResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /stream/venue/access:
    post:
      tags:
        - "Datacore"
      summary: "Get access to the Datacore Streaming API for a venue"
      description: "This call will return information about how to access the the DataCore Streaming API service for a venue."
      operationId: "getStreamAuthVenue"
      x-hideTryItPanel: true
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Credentials'
                - $ref: '#/components/schemas/CredentialsUser'
              additionalProperties: false
              properties:
                venueId:
                    $ref: '#/components/schemas/VenueId'
                sport:
                    $ref: '#/components/schemas/Sport'
                scopes:
                    $ref: '#/components/schemas/StreamScopesVenue'
                includePort:
                    $ref: '#/components/schemas/IncludePort'
              required:
                - venueId
                - sport
                - scopes

      responses:
        200:
          $ref: '#/components/responses/StreamAuthResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /stream/fixture/specific:
    post:
      tags:
        - "Datacore"
      summary: "Get access to the Datacore Streaming API for a specific topic"
      description: "This call will return information about how to access the Datacore Streaming API service. 
        <p>
        In most cases this call should <b>NOT</b> be used, the '/stream/access' call should be used instead.  This call would only be used to connect to a specific topic. Note: The topic names are not guaranteed to be the same on subsequent calls.
        </p>"
      operationId: "getTokenStreamSpecific"
      x-hideTryItPanel: true
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              oneOf:
                - $ref: '#/components/schemas/Credentials'
                - $ref: '#/components/schemas/CredentialsUser'
              properties:
                topics:
                  description: "An array of topic names that you want access to."
                  type: "array"
                  uniqueItems: true
                  items:
                    type: string
                    example: '/stream/basketball/b1a23/009e9276-5c80-11e8-9c2d-fa7ae01bbebc/009e9276-5c80-11e8-9c2d-fa7ae01bbebc/scoreboard'
                scopes:
                  $ref: '#/components/schemas/StreamScopes'
              required:
                - streams

      responses:
        200:
          $ref: '#/components/responses/StreamAuthResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /products/token:
    post:
      tags:
        - "Products"
      summary: "Get an Access Token for access to a product."
      description: "This API calls are used primarily by Synergy Sports internal systems to authenticate to products other than Datacore."
      operationId: "getTokenProdUser"
      x-hideTryItPanel: true
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                userIdentityToken:
                  $ref: '#/components/schemas/UserIdentityToken'
                product:
                  description: "The product you want the token for. Valid options available for the user can be obtained from the `products/list` call."
                  type: "string"
                  example: "videostream_manager"
                customerId:
                  description: "The customerId for the product you want a token for. Valid options available for the user can be obtained from the `customers/list` call."
                  type: "string"
                  example: 345
                scopes:
                  description: "A list of permission scopes that you want for this token.  If not provided then all available permissions will be added. You would use this if you want your token to have less permissions that you are normally allowed."
                  type: "array"
                  uniqueItems: true
                  items:
                    type: string
                    example: 'read:organization'
                  example: ['read:organization','write:organization']
              required:
                - userIdentityToken
                - product
                - customerId
      responses:
        200:
          $ref: '#/components/responses/TokenResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /list/customers:
    post:
      tags:
        - "Users"
      summary: "Get a list of customers"
      description: "Get a list of customers to which a user is linked."
      operationId: "getUserCustomerList"
      x-hideTryItPanel: true
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                userIdentityToken:
                  $ref: '#/components/schemas/UserIdentityToken'
                product:
                  description: "Only list customers that have a certain product."
                  type: "string"
                  example: "videostream_manager"
              required:
                - userIdentityToken
      responses:
        200:
          $ref: '#/components/responses/UserCustomerListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /list/products:
    post:
      tags:
        - "Users"
      summary: "Get a list of products"
      description: "Get a list of products for a customer to which a user is linked."
      operationId: "getTokenUserList"
      x-hideTryItPanel: true
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                userIdentityToken:
                  $ref: '#/components/schemas/UserIdentityToken'
                customerId:
                  $ref: '#/components/schemas/CustomerId'
              required:
                - userIdentityToken
                - customerId
      responses:
        200:
          $ref: '#/components/responses/UserProductListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /info/scopes/authorized:
    get:
      tags:
        - "Token Information"
      summary: "Return the list of authorized scopes/permissions for your token"
      description: "Get a list of scopes/permissions currently authorized for your token."
      operationId: "getTokenInfoScopeAuthorized"
      x-hideTryItPanel: true
      responses:
        200:
          $ref: '#/components/responses/ScopeListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /info/scopes/available:
    get:
      tags:
        - "Token Information"
      summary: "Return the list of all scopes/permissions that you could request for your token"
      description: "Get a list of scopes/permissions available for you to request for your token."
      operationId: "getTokenInfoScopeAvailable"
      x-hideTryItPanel: true
      responses:
        200:
          $ref: '#/components/responses/ScopeListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /info/access/authorized:
    get:
      tags:
        - "Token Information"
      summary: "Return the list of the currently authorized access for your token"
      description: "Get a list of access currently authorized for your token. This call will only work where the token is for `datacore`."
      operationId: "getTokenInfoAccessAuthorized"
      x-hideTryItPanel: true
      responses:
        200:
          $ref: '#/components/responses/AccessListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /info/access/available:
    get:
      tags:
        - "Token Information"
      summary: "Return the list of all access that you could request for your token"
      description: "Get a list of access available for you to request for your token. This call will only work where the token is for `datacore`."
      operationId: "getTokenInfoAccessAvailable"
      x-hideTryItPanel: true
      responses:
        200:
          $ref: '#/components/responses/AccessListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  responses:
    TokenResponse:
      description: "Success"
      content:
        application/json:
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  token:
                    type: "string"
                    description: A JWT giving you access to the resources you requested.
                    example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlRoaXMgaXMganVzdCBhIGR1bW15IGV4YW1wbGUgdG9rZW4uIFlvdSBkaWRuJ3QgcmVhbGx5IGV4cGVjdCBhbnl0aGluZyBpbnRlcmVzdGluZyBoZXJlIGRpZCB5b3U_IiwiaWF0IjoxNTE2MjM5MDIyfQ.kh8vizGTBesLJgW0XuFh4cQ9dhmtOIasg6Hb1Z_KgHg"
                  tokenType:
                    description: The type of token
                    type: "string"
                    example: "bearer"
                  expiresIn:
                    description: How long, in seconds, the token is valid for
                    type: "string"
                    format: "number"
                    example: 3600
              meta:
                $ref: '#/components/schemas/ResponseMetaData'
    StreamAuthResponse:
      description: "Success"
      content:
        application/json:
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  url:
                    description: A url that you should connect to to get access to the data.
                    type: "string"
                    format: "url"
                    example: "wss://a3q4n6jdf6vh3t-ats.iot.eu-west-1.amazonaws.com/mqtt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIASEQ6JOTPW4ZDZZFF%2F20200313%2Feu-west-1%2Fiotdevicegateway%2Faws4_request&X-Amz-Date=20200313T013641Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-Signature=4d36c67773a04f540b53d28673c3388763d7bd6eca5ad5a16a03e31cfa243288&X-Amz-Security-Token=FwoGZXIvYXdzEGMaDGWqMYxy6Ki%2BQXmx%2BCLKA1CqZhw3o%2BScGqcPJy%2FWjA5IcMN9TKbfPX5m1GCKmh%2BX%2F4eqzAY4KZzx8v54okLVBwcLWEfyFKhK8xIUOXFnfy8rhpcXuHyMbY1dhLsvZe7jvBUZna3KSaKRbhEgctqdxkasJTNULSCjHstuNaLpY44bbyPSdiSpfH3l6D%2B%2BhIdnbIiSWCoQCeuF%2B6HUf0aWKMejPGmpBaTOZZCB%2BvauinBj1bd%2BVceDn7LAI3Ff2lOAkGbBnyptfbo%2B%2BhVbuaYCKR0lnmylW2q80oK%2FXoQ9Q%2FuLLVmakTFm3h5Bfq1cIBF5TXl6L3yHd3Pdy5XJ1uuOWLRNd122kl6508yxj8t04aL%2BOujvO2iL9moMRkJ9Xst6NkiUJ0VGV8GO25HfsC2j1hpJMS%2FhATjufRT%2BP3ZNG2EAs5Uae3hBzhsh7lqQcglOOrkFwlUuslJ9YjgQt4MTIV7vQR0Z2xhgRE%2BzvGF5RpsLPg1Nv1e2vnpPZrRWYrJxeirdxP5yVeVi5jsqjFnPfH9BUwwbM54oSKuw0UV5RdV%2FjKkykpPlPZJFA28r5KQH9Yv%2B47Ujc9LZN42ft8cAiTcjvy1IpREW58zTzzOu6NXfdtBIvch1ZVDoKKjHq%2FMFMi3ypX%2BR4xXt2QmkclFTdeMGr7YFlC66U7KevUMWJvE3ErKTUYXG5CB2U0Ydw8c%3D"

                  clientId:
                    description: The clientId to be used on the connection
                    type: "string"
                    example: "stream-25fe57d4-fe21-4429-a46e-f4e007977550"
                  topics:
                    description: >
                        A list of topics that can be subscribed/published to for this connection. For each scope you requested you will receive a topic that should be used for that scope.


                        You will also receive an additional topic with the scope of `read:response`.  Any specific response/error messages from the system about the data you provide will be sent on this topic.


                        By default, topics will only send new 'data' that is sent/generated after the connection.  For a number of topics an additional topic ending in `_catchup` is also provided.  If you subscribe to this topic it will send the last value of the corresponding topic when you subscribe to it.
                    type: "array"
                    items:
                        type: object
                        properties:
                          topic:
                            description: The topic that can be subscribed/published to for this scope
                            type: "string"
                            example: "stream/basketball/venue/ba53b55c-f6c6-11e9-802a-5aa538984bd8/scoreboard"
                          scope:
                            description: The scope for this stream
                            type: "string"
                            example: "read:stream_scoreboard"
                          permission:
                            description: The permission (read/write) for this topic
                            type: "string"
                            example: "read"

              meta:
                $ref: '#/components/schemas/ResponseMetaData'
    AccessListResponse:
      description: "Access List Response"
      content:
        application/json:
          schema:
            type: "object"
            properties:
              data:
                type: object
                properties:
                    organizations:
                        type: "array"
                        items:
                          type: "object"
                          properties:
                            sport:
                              description: The sport for the organization
                              type: "string"
                              example: 'basketball'
                            organizationId:
                              description: The unique code of the organization
                              type: "string"
                              example: 'b1a23'
                            nameLocal:
                              description: The name of the organization (in local language)
                              type: "string"
                              example: 'National Basketball League'
                            nameLatin:
                              description: The name of the organization (in latin characters)
                              type: "string"
                              example: 'National Basketball League'
                    organizationGroups:
                        type: "array"
                        items:
                          type: "object"
                          properties:
                            sport:
                              description: The sport for the organization group
                              type: "string"
                              example: 'basketball'
                            orgGroup:
                              description: The unique code of the organization group
                              type: "string"
                              example: 'aubb'
              meta:
                $ref: '#/components/schemas/ResponseMetaData'
    ScopeListResponse:
      description: "Scope List Response"
      content:
        application/json:
          schema:
            type: "object"
            properties:
              data:
                type: "array"
                items:
                  description: The scope/permission
                  type: "string"
                  example: 'read:organization'
              meta:
                $ref: '#/components/schemas/ResponseMetaData'
    UserCustomerListResponse:
      description: "Success"
      content:
        application/json:
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  customers:
                    type: "array"
                    items:
                      type: "object"
                      properties:
                        customerId:
                          description: The id of the customer
                          type: "string"
                          format: "number"
                          example: 1
                        name:
                          description: The name of the customer
                          type: "string"
                          example: "Test Customer"
              meta:
                $ref: '#/components/schemas/ResponseMetaData'
    UserProductListResponse:
      description: "Success"
      content:
        application/json:
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  products:
                    type: "array"
                    items:
                      type: "object"
                      properties:
                        code:
                          description: The product code
                          type: "string"
                          example: "videostream_manager"
                        name:
                          description: The product name
                          type: "string"
                          example: "Videostream Manager"
                        subProducts:
                          description: Some products may also have sub products.
                          type: "array"
                          items:
                              type: "object"
                              properties:
                                subProductId:
                                  description: The id of the sub-product
                                  type: "string"
                                  format: "number"
                                  example: 1
                                subProductName:
                                  description: The name of the sub-product
                                  type: "string"
                                  example: "Sub product 1"
              meta:
                $ref: '#/components/schemas/ResponseMetaData'

    ErrorResponse:
      description: "Error"
      content:
        application/json:
          schema:
            properties:
              error:
                $ref: '#/components/schemas/ErrorModel'
              meta:
                $ref: '#/components/schemas/ResponseMetaData'
            type: object
  schemas:
    ErrorListModel:
      properties:
        code:
          description: HTTP Error code indicating the type of error.
          example: 400
          format: int32
          type: integer
        message:
          description: A message indicating the reason for the error
          example: Field 'credentialId' is required
          type: string
        reason:
          description: A short code indicating the type of error
          enum:
          - INVALID_DATA
          - NOT_FOUND
          - NOT_AUTHORISED
          - ERROR
          example: INVALID_DATA
      type: object
    ErrorModel:
      properties:
        code:
          description: HTTP Error code indicating the type of error.  If there are
            multiple errors, then this will be the code of the first one.
          example: 400
          format: int32
          type: integer
        errors:
          items:
            $ref: '#/components/schemas/ErrorListModel'
          type: array
        message:
          description: A message indicating the reason for the error. If there are
            multiple errors, then this is the message for the first one.
          example: Field 'credentialId' is required
          type: string
      type: object
    ResponseMetaData:
      properties:
        code:
          description: The HTTP response code for this request
          example: 200
          type: integer
        codeVersion:
          description: A string indicating the version of the code that handled this
            request
          example: d6cd1e2bd19e03a81132a23b2025920577f84e37
          type: string
        generationTime:
          description: The number of seconds taken to generate this request.
          example: 0.011604
          format: float
          type: number
        time:
          description: The date/time this request was made (in UTC).
          example: 2018-06-05 23:43:41.227584
          format: date-time
          type: string
        version:
          description: The version of the API in use for this call
          example: 1
          type: string
      type: object
    StreamScopesVenue:
      description: "A list of permission scopes that you want for this call. If you request scopes that you do not have permission for, then the call will fail.

        Available options:

        >- write:stream_scoreboard

        >- read:stream_scoreboard
        "
      type: "array"
      uniqueItems: true
      items:
        type: string
        example: 'write:stream_scoreboard'
      example: ['read:stream_scoreboard','write:stream_scoreboard']
    StreamScopes:
      description: "A list of permission scopes that you want for this call.  If you request scopes that you do not have permission for, then the call will fail.

        Available options:
        
        >- write:stream_events
        
        - write:stream_tracking
        
        - write:stream_biometrics
        
        - write:stream_scoreboard
        
        - read:stream_events
        
        - read:stream_tracking
        
        - read:stream_biometrics
        
        - read:stream_scoreboard
        
        - read:stream_status
        
        - read:stream_statistics
        
        - read:stream_statistics_periods
        
        - read:stream_play_by_play
        
        - read:stream_persons
        
            "
      type: "array"
      uniqueItems: true
      items:
        type: string
        example: 'read:stream_events'
      example: ['read:stream_events','read:stream_statistics']

    Credentials:
        type: object
        title: Application Credentials
        properties:
            credentialId:
              description: "Credential identifier."
              type: "string"
              example: "e50u42059u405u43503u5"
            credentialSecret:
              description: "Secret code related to the `credentialId`."
              type: "string"
              example: "e50u42059u405u43503u5"
        required:
          - credentialId
          - credentialSecret
    CredentialsUser:
        type: object
        title: Individual User Credentials
        properties:
            userIdentityToken:
              $ref: '#/components/schemas/UserIdentityToken'
            applicationId:
              description: "Id of application to authenticate to. Used in conjunction with userIdentityToken."
              type: "string"
              format: "number"
              example: 34
        required:
          - userIdentityToken
          - applicationId
    UserIdentityToken:
      description: "A user token received on login to the single sign on system."
      type: "string"
      example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGUuYXV0aDAuY29tLyIsImF1XCI6Imh0dHBzOi8vYXBpLmV4YW1wbGUuY29tL2NhbGFuZGFyL3YxLyIsInN1YiI6InVzcl8xMjMiLCJpYXQiOjE0NTg3ODU3OTYsImV4cCI6MTQ1ODg3MjE5Nn0.CA7eaHjIHz5NxeIJoFK9krqaeZrPLwmEmgI_XiQiIkQ"
    Sport:
      description: "The sport for this call"
      type: "string"
      enum:
        - basketball
        - baseball
        - volleyball
        - football
        - handball
        - icehockey
        - hockey
        - badminton
        - futsal
      example: "basketball"
    FixtureId:
      description: "The Id of the fixture you want to subscribe to."
      type: "string"
      example: "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
    VenueId:
      description: "The Id of the venue you want to subscribe to."
      type: "string"
      example: "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
    CustomerId:
      description: "The id of the customer."
      type: "string"
      format: "number"
      example: 456
    IncludePort:
      description: "If `true`, the returned signed WebSocket endpoint URL will include the port (default: `false`). Some websocket/mqtt libraries require this."
      type: "boolean"
      example: false
