swagger: "2.0"
schemes:
  - https
host: sandbox.whapi.com
basePath: /v2/sessions
info:
  contact:
    email: platform@williamhill.com
    name: William Hill Labs
    url: http://developer.williamhill.com
    x-twitter: WilliamHill
  description: "The William Hill Sessions API uses a central authentication service (CAS*) on all resources that require access to a customer’s account or betting functionality. To authenticate, you’ll need to supply a sportsbook username and password, in return you will be given an authentication ticket, which you can use on the majority of requests found within our services. <br /><br /><br /> The Sessions API should be used whenever you want to login a customer and:<br /><br /> <ul> <li>continue to use the William Hill API for that customer’s transactions</li> <li>use other CAS-enabled William Hill services outside the suite of APIs</li> </ul> <br /> CAS is an enterprise Single Sign-On solution for web services (see https://wiki.jasig.org/display/CAS/Home). It is used by many William Hill services. <br /> Note: all requests must be executed over HTTPS and include an API key and secret.<br /><br /><br /> <b>Authentication Ticket Expiration Times</b><br /><br /> When a customer is logged in using the Sessions API, they are given an Authentication Ticket; using this ticket on subsequent API requests gives you access to account activities (such as placing a bet, deposits, etc). However, this ticket is only valid for a given period of time depending on how it is used. If the ticket is used and then has a period of inactivity longer than 7,200 seconds (2 hours), then the ticket will expire and further requests using the ticket will be denied - in effect, a customer has been logged out and will need to authenticate again. <br /><br /><br /> Normally, any ticket issued only has a maximum life expectancy of 28,000 seconds (8 hours) after which it can no longer be used, even if it has been used regularly. The customer again will be effectively logged out and will need to authenticate again. If you wish to avoid this, you need to set the query parameter extended to Y, which will enable your application to generate a ticket valid for 60 days without expiring due to inactivity. <br />"
  title: Sessions API
  version: 2.0.0
  x-apisguru-categories:
    - entertainment
  x-logo:
    url: https://twitter.com/WillHillHelp/profile_image?size=original
  x-origin:
    - format: swagger
      url: https://developer.williamhill.com/wh-docs/docs-sdks/sessions/swagger/docs
      version: "2.0"
  x-providerName: whapi.com
  x-serviceName: sessions
parameters:
  param_apiKey:
    description: A unique identifier of your application that is generated by the API portal.
    in: header
    name: apiKey
    pattern: ^[a-zA-Z0-9]{19,50}$
    required: true
    type: string
    x-eg: l7xxa54460c573b5497c9b24b505xxxxxxxx
  param_apiSecret:
    description: Another unique identifier for your application.
    in: header
    name: apiSecret
    pattern: ^[a-zA-Z0-9]{19,50}$
    required: true
    type: string
    x-eg: l7xxa54460c573b5497c9b24b505xxxxxxxx
  param_exclude:
    collectionFormat: csv
    description: Specify fields from the default to exclude (Comma Separated List)
    in: query
    items:
      type: string
    name: exclude
    required: false
    type: array
    x-eg: expiryDateTime
  param_fields:
    collectionFormat: csv
    description: Specify an absolute field list to return (Comma Separated List)
    in: query
    items:
      type: string
    name: fields
    required: false
    type: array
    x-eg: extended
  param_include:
    collectionFormat: csv
    description: Specify fields in addition to the default to return (Comma Separated List)
    in: query
    items:
      type: string
    name: include
    required: false
    type: array
    x-eg: extended
  param_languageAsPerTerritory:
    default: true
    description: Defines response field name language, true (default) returns in language defined by territory, false returns in English
    in: query
    name: languageAsPerTerritory
    pattern: ^(true|false)$
    required: false
    type: string
    x-eg: false
  param_territory:
    description: Territory from which request originates
    in: header
    name: territory
    pattern: ^(COM|ES|IT)$
    required: false
    type: string
    x-eg: ES
  param_tgt:
    description: Ticket Granting Ticket obtained from a previous request
    in: path
    name: tgt
    pattern: ^[a-zA-Z][a-zA-Z0-9-]{39,100}$
    required: true
    type: string
paths:
  /tickets:
    post:
      consumes:
        - application/json
      description: "Logs in a customer by obtaining an authentication ticket. It can then be used directly with the other William Hill APIs to access a customer’s sportsbook account, place a bet, etc. "
      operationId: logIn
      parameters:
        - $ref: "#/parameters/param_apiKey"
        - $ref: "#/parameters/param_apiSecret"
        - $ref: "#/parameters/param_fields"
        - $ref: "#/parameters/param_include"
        - $ref: "#/parameters/param_exclude"
        - $ref: "#/parameters/param_territory"
        - $ref: "#/parameters/param_languageAsPerTerritory"
        - description: Login request object
          in: body
          name: login
          required: true
          schema:
            $ref: "#/definitions/loginRequest"
      produces:
        - application/json
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/session"
        "401":
          description: Login - failed
          schema:
            $ref: "#/definitions/sessionsErrors"
        "403":
          description: Forbidden
          examples:
            application/json:
              errors:
                - code: "20503"
                  message: Account under self-exclusion
                - code: "20504"
                  message: Account locked.
                - code: "20505"
                  message: Account inactive.
                - code: "20506"
                  message: Account closed.
                - code: "20507"
                  message: Age verification required.
                - code: "20508"
                  message: Account under self-exclusion, reactivation available.
                - code: "20509"
                  message: Timeout applied.
                - code: "20503"
                  message: Account under self-exclusion
                - code: "20512"
                  message: Account Suspended
                - code: "20513"
                  message: Max Linked Accounts
                - code: "20514"
                  message: Account Closed By Player
          schema:
            $ref: "#/definitions/sessionsErrors"
        "404":
          description: Application metadata not configured correctly
          schema:
            $ref: "#/definitions/sessionsErrors"
      summary: Logs in a customer and obtains an authentication ticket.
      tags:
        - Sessions
      x-canReturnErrors:
        - 20501
        - 20503
        - 20504
        - 20505
        - 20506
        - 20507
        - 20508
        - 20509
        - 20512
        - 20513
        - 20514
  "/tickets/{tgt}":
    delete:
      description: Logs out a customer.
      operationId: logOut
      parameters:
        - $ref: "#/parameters/param_apiKey"
        - $ref: "#/parameters/param_apiSecret"
        - $ref: "#/parameters/param_tgt"
        - $ref: "#/parameters/param_territory"
        - $ref: "#/parameters/param_languageAsPerTerritory"
      produces:
        - application/json
      responses:
        "200":
          description: Success - Logout
          schema:
            $ref: "#/definitions/logoutresponse"
        "403":
          description: Forbidden
          schema:
            $ref: "#/definitions/sessionsErrors"
        "404":
          description: Resource Not Found
          examples:
            application/json:
              errors:
                - code: "20511"
                  field: target
                  message: TGT ticket could not be found.
          schema:
            $ref: "#/definitions/sessionsErrors"
      summary: Log out a customer.
      tags:
        - Sessions
      x-canReturnErrors:
        - 20511
    get:
      description: Checks the validity of a session ticket.
      operationId: validateSession
      parameters:
        - $ref: "#/parameters/param_apiKey"
        - $ref: "#/parameters/param_apiSecret"
        - $ref: "#/parameters/param_tgt"
        - $ref: "#/parameters/param_territory"
        - $ref: "#/parameters/param_languageAsPerTerritory"
      responses:
        "200":
          description: The validity status of the tgt
          examples:
            application/json:
              valid: true
          schema:
            $ref: "#/definitions/ticketvalidityresponse"
        "404":
          description: Resource Not Found
          examples:
            application/json:
              errors:
                - code: "20511"
                  field: target
                  message: TGT ticket could not be found.
          schema:
            $ref: "#/definitions/sessionsErrors"
      summary: Checks the validity of a session ticket.
      tags:
        - Sessions
      x-canReturnErrors:
        - 20511
  "/tickets/{tgt}/serviceTicket":
    get:
      description: Obtains a one-time Service Ticket that can be used to access other CAS enabled William Hill services that are not available through the standard suite of APIs. You first need to have logged in a customer to obtain an Authentication Ticket.
      operationId: getServiceTicket
      parameters:
        - $ref: "#/parameters/param_apiKey"
        - $ref: "#/parameters/param_apiSecret"
        - $ref: "#/parameters/param_tgt"
        - $ref: "#/parameters/param_territory"
        - $ref: "#/parameters/param_languageAsPerTerritory"
        - description: The target URL of the CAS enabled service that you want to use with the service ticket.
          in: query
          name: target
          required: true
          type: string
        - $ref: "#/parameters/param_fields"
        - $ref: "#/parameters/param_include"
        - $ref: "#/parameters/param_exclude"
      produces:
        - application/json
      responses:
        "200":
          description: Success - Service Ticket created
          examples:
            application/json:
              location: http://www.example.com/
              ticket: ST-861-kM1s6zg4QBb6xf4CF4oe-brsux349
          schema:
            $ref: "#/definitions/serviceTicket"
        "403":
          description: Forbidden
          examples:
            application/json:
              errors:
                - code: "20510"
                  field: target
                  message: Target service not established
          schema:
            $ref: "#/definitions/sessionsErrors"
        "404":
          description: Resource Not Found
          examples:
            application/json:
              errors:
                - code: "20511"
                  field: target
                  message: TGT ticket could not be found.
          schema:
            $ref: "#/definitions/sessionsErrors"
      summary: Obtains a one-time Service Ticket that can be used to access other William Hill services.
      tags:
        - Sessions
      x-canReturnErrors:
        - 20501
        - 20511
definitions:
  error:
    properties:
      code:
        description: A unique William Hill identifier for the error
        type: string
      field:
        description: To help pinpoint the exact parameter where a request has failed
        type: string
      message:
        description: A unique William Hill text string to enable you to identify the error
        type: string
    type: object
  loginRequest:
    properties:
      extended:
        default: false
        description: "Whether extended login or normal login is required. If the parameter is set to Y your application will generate an authentication ticket valid for a period of 60 days, without expiring due to inactivity. If the parameter is left blank or set to N this means your application will support the normal expiry times for tickets: The ticket expires after 2 hours of inactivity. The ticket is valid for a maximum of 8 hours after it has been issued."
        type: boolean
      password:
        description: Customer Password
        pattern: ^[a-zA-Z0-9_\-]{6,15}$
        type: string
      username:
        description: Customer Username
        pattern: ^[A-Za-z0-9_@\ \.]{5,15}$
        type: string
    required:
      - username
      - password
    type: object
  logoutresponse:
    properties:
      success:
        type: boolean
    type: object
  serviceTicket:
    properties:
      location:
        description: This is the URL of the target service sent in the request. This is a combination of the endpoint and the ticket for future operations such as DELETE.
        type: string
      ticket:
        description: The TGT ticket
        type: string
    required:
      - ticket
    type: object
  session:
    properties:
      expiryDateTime:
        description: The UTC time when the ticket expires.
        type: string
      extended:
        description: The value you have selected previous to executing the request. If the value is Y, this enables your application to generate a ticket valid for 60 days without expiring due to inactivity.
        type: boolean
      location:
        description: This is the URL of the target service sent in the request. This is a combination of the endpoint and the ticket for future operations such as DELETE.
        type: string
      temporaryPassword:
        description: Indicates that the account has a temporary password set and hence the user must be prompted to change their password.
        type: boolean
      temporaryPasswordUrl:
        description: Url for user to change password. A TGT must be added to the URL
        type: string
      ticket:
        description: The TGT ticket
        type: string
    required:
      - ticket
      - expiryDateTime
    type: object
  sessionsErrors:
    properties:
      errors:
        items:
          $ref: "#/definitions/error"
        type: array
    type: object
  ticketvalidityresponse:
    properties:
      valid:
        type: boolean
    type: object
x-customerrors:
  - code: 20501
    message: Credentials failed to validate.
    status: 401
  - code: 20502
    message: Target service not established.
    status: 403
  - code: 20503
    message: Account under self-exclusion.
    status: 403
  - code: 20504
    message: Account locked.
    status: 403
  - code: 20505
    message: Account inactive.
    status: 403
  - code: 20506
    message: Account closed.
    status: 403
  - code: 20507
    message: Age verification required.
    status: 403
  - code: 20508
    message: Account under self-exclusion, reactivation available.
    status: 403
  - code: 20509
    message: Timeout applied.
    status: 403
  - code: 20510
    message: Target service not established.
    status: 403
  - code: 20511
    message: TGT ticket could not be found.
    status: 404
  - code: 20512
    message: Account Suspended
    status: 403
  - code: 20513
    message: Max Linked Accounts
    status: 403
  - code: 20514
    message: Account Closed By Player
    status: 403
x-docchapters:
  - fieldSelection
  - apiSummary
  - headAndOptions
  - docsAndSdks
  - errorHandling
  - statusCodes
