#%RAML 0.8
title: OAuth API V3
baseUri: https://api.us1.covisint.com/oauth/v3
protocols:
- HTTPS
securitySchemes:
- basic:
    type: Basic Authentication
schemas:
- resourceReference: |
    {
      "id" : "http://api.covisint.com/schema/resourceReference",
      "$schema" : "http://json-schema.org/draft-04/schema",
      "description" : "Schema representing links",
      "type" : "object",
      "properties" : {
        "id" : {
          "type" : "string",
          "maxLength" : 36,
          "description" : "The unique identifier for the resource.",
          "required": true
        },
        "type" : {
          "type" : "string",
          "description" : "The type of the resource."
        },
        "realm" : {
          "type" : "string",
          "description" : "The realm of the resource."
        }
      }
    }
- namedResourceReference: "{\n  \"id\" : \"http://api.covisint.com/schema/namedScopedResource\",\n
    \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n  \"type\" : \"object\",\n
    \ \"description\" : \"Expands on the basic resource reference and adds internationalized
    name and description.\",\n  \"extends\" : {\n        \"$ref\" : \"http://api.covisint.com/schema/resourceReference#\"\n
    \ },\n  \"properties\" : {\n     \"name\" : {  \n       \"description\": \"Internationalized
    resource name.\",\n       \"$ref\" : \"http://api.covisint.com/idm/schema/internationalString#\"\n
    \    },\n     \"description\" : {  \n       \"description\": \"Internationalized
    resource description.\",\n       \"$ref\" : \"http://api.covisint.com/idm/schema/internationalString#\"\n
    \    }\n   }\n}\n"
- resource: "{\n  \"id\" : \"http://api.covisint.com/schema/resource\",\n  \"$schema\"
    : \"http://json-schema.org/draft-04/schema\",\n  \"description\" : \"Core schema\",\n
    \ \"definitions\" : {\n    \"resource\" : {\n      \"id\" : \"resource\",\n      \"type\"
    : \"object\",\n      \"description\" : \"A basic resource.\",\n      \"properties\"
    : {\n        \"id\" : {\n          \"type\" : \"string\",\n          \"maxLength\"
    : 64,\n          \"description\" : \"The unique identifier for this resource.\",\n
    \         \"required\": true\n        },\n        \"version\": {\n          \"type\"
    : \"number\",\n          \"minimum\" : 0,\n          \"maximum\" : 9223372036854775807,\n
    \         \"description\" : \"The current version for this resource.  Exists once
    the resource has been saved. This is mandatory for PUT requests, but should not
    be supplied for POST requests.\",\n          \"required\": false\n        },\n
    \       \"creator\" : {\n          \"type\" : \"string\",\n          \"maxLength\"
    : 64,\n          \"description\" : \"The creator of this resource. This is mandatory
    if x-requestor header is NOT available\",\n          \"required\": false\n        },\n
    \       \"creatorAppId\" : {\n          \"type\" : \"string\",\n          \"maxLength\"
    : 64,\n          \"description\" : \"The application id of the creator of this
    resource.\",\n          \"required\": false\n        },\n        \"creation\"
    : {\n          \"type\" : \"number\",\n          \"minimum\" : 0,\n          \"maximum\"
    : 9223372036854775807,\n          \"description\" : \"If this value is provided
    in a POST / PUT request body, it will be ignored and system will generate value
    as time, in milliseconds since the epoch, when this resource was created or upda\",\n
    \         \"required\": false            \n        }\n      }\n    }\n  }\n}\n"
- resourceV2: "{\n  \"id\" : \"http://api.covisint.com/schema/resourceV2\",\n  \"$schema\"
    : \"http://json-schema.org/draft-04/schema\",\n  \"description\" : \"Core schema\",\n
    \ \"definitions\" : {\n    \"resource\" : {\n      \"id\" : \"resourceV2\",\n
    \     \"type\" : \"object\",\n      \"description\" : \"A basic resource (version
    V2).\",\n      \"properties\" : {\n        \"id\" : {\n          \"type\" : \"string\",\n
    \         \"maxLength\" : 64,\n          \"description\" : \"The unique identifier
    for this resource.\",\n          \"required\": true\n        },\n        \"version\":
    {\n          \"type\" : \"string\",\n          \"description\" : \"The current
    version for this resource. Exists once the resource has been saved. This is mandatory
    for PUT requests, but should not be supplied for POST requests.\",\n          \"required\":
    false\n        },\n        \"creator\" : {\n          \"type\" : \"string\",\n
    \         \"maxLength\" : 64,\n          \"description\" : \"The creator of this
    resource. This is mandatory if x-requestor header is NOT available\",\n          \"required\":
    false\n        },\n        \"creatorAppId\" : {\n          \"type\" : \"string\",\n
    \         \"maxLength\" : 64,\n          \"description\" : \"The application id
    of the creator of this resource.\",\n          \"required\": false\n        },\n
    \       \"creation\" : {\n          \"type\" : \"number\",\n          \"minimum\"
    : 0,\n          \"maximum\" : 9223372036854775807,\n          \"description\"
    : \"If this value is provided in a POST / PUT request body, it will be ignored
    and system will generate value as time, in milliseconds since the epoch, when
    this resource was created or upda\",\n          \"required\": false            \n
    \       }\n      }\n    }\n  }        \n}\n"
- realmScopedResource: |
    {
      "id" : "http://api.covisint.com/schema/realmScopedResource",
      "$schema" : "http://json-schema.org/draft-04/schema",
      "type" : "object",
      "description" : "Expands on the base resource and adds a realm attribute.",
      "extends" : {
            "$ref" : "http://api.covisint.com/schema/resource#"
      },
      "properties" : {
        "realm" : {
          "type" : "string",
          "maxLength" : 25,
          "pattern" : "^[A-Za-z0-9]{2,25}$",
          "description" : "The realm in which this resource is being created. This is mandatory if x-realm header is NOT available",
          "required": false
        }
      }
    }
- realmScopedResourceV2: "{\n  \"id\" : \"http://api.covisint.com/schema/realmScopedResourceV2\",\n
    \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n  \"type\" : \"object\",\n
    \ \"description\" : \"A realm scoped resource (version V2). Expands on the base
    resource (version V2) and adds a realm attribute.\",\n  \"extends\" : {\n        \"$ref\"
    : \"http://api.covisint.com/schema/resourceV2#\"\n  },\n  \"properties\" : {\n
    \   \"realm\" : {\n      \"type\" : \"string\",\n      \"maxLength\" : 25,\n      \"pattern\"
    : \"^[A-Za-z0-9]{2,25}$\",\n      \"description\" : \"The realm in which this
    resource is being created. This is mandatory if x-realm header is NOT available\",\n
    \     \"required\": false\n    }\n  }\n} \n"
- errorResponseSchema: "{\n  \"id\" : \"http://api.covisint.com/schema/errorResponseSchema\",\n
    \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n  \"type\" : \"object\",\n
    \ \"description\" : \"Representation of an HTTP 4xx/5xx error response.\",\n  \"properties\"
    : {\n    \"status\" : { \n      \"type\" : \"number\",\n      \"minimum\" : 400,\n
    \     \"maximum\" : 599,\n      \"description\" : \"The HTTP status code.\",\n
    \     \"required\": true\n    },\n    \"apiMessage\" : { \n      \"type\" : \"string\",\n
    \     \"description\" : \"A helpful, human-readable description of the error,
    useful for basic diagnostics.\" \n    },\n    \"apiStatusCode\" : {\n      \"type\"
    : \"string\",\n      \"description\" : \"The API-specific status code.\"\n    }\n
    \ }\n}\n"
- serviceCode: "{\n  \"id\" : \"http://api.covisint.com/schema/serviceCodes\",\n  \"$schema\"
    : \"http://json-schema.org/draft-04/schema\",\n  \"type\": \"object\",\n  \"description\":
    \"The site/service/location codes granted along with a service.\",\n  \"properties\":
    {\n    \"code\": { \"type\": \"string\", \"required\": true, \"maxLength\": 200,
    \"description\": \"The code value.\" },\n    \"codeKind\": { \"type\": \"string\",
    \"required\": true, \"maxLength\": 36, \"description\": \"The associated business
    unit.\" }\n  }\n}     \n"
- serviceCodes: |
    {
      "type" : "array",
      "description" : "The site/service/location codes granted along with the service, if any.",
      "items" : { "$ref" : "http://api.covisint.com/schema/serviceCode#"},
      "required": false
    }
- address: |
    {
      "id" : "http://api.covisint.com/idm/schema/address",
      "$schema" : "http://json-schema.org/draft-04/schema",
      "type" : "object",
      "description" : "A container for the subject's address elements.",
      "properties" : {
        "type" : "string",
        "streets" : {
            "type" : "array",
            "description" : "An array of address streets (i.e. address line 1, 2, 3).",
            "minItems" : 0,
            "items" : {
              "type": "string",
              "maxLength" : 255
            }
          },
          "city" : { "type" : "string", "maxLength" : 60, "description" : "The city name." },
          "state" : { "type" : "string", "maxLength" : 60, "description" : "The state/province name or code." },
          "postal" : { "type" : "string", "maxLength" : 10, "description" : "The postal or zip code." },
          "country" : { "type" : "string", "minLength" : 2, "maxLength" : 3, "description" : "The ISO country code. http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2"}
      }
    }
- phone: "{\n  \"id\" : \"http://api.covisint.com/idm/schema/phone\",\n  \"$schema\"
    : \"http://json-schema.org/draft-04/schema\",\n  \"type\" : \"object\",\n    \"description\"
    : \"A container for phone number details.\",\n    \"properties\" : {\n      \"number\"
    : { \"type\" : \"string\",\"maxLength\" : 100, \"description\" : \"The phone number.\"
    },\n      \"type\" : { \"enum\" : [ \"main\", \"mobile\", \"fax\" ], \"description\"
    : \"The phone number type.\" }\n    },\n    \"required\" : [ \"type\" ]\n}             \n"
- internationalString: |
    {
      "id": "http://api.covisint.com/idm/schema/internationalString",
      "$schema": "http://json-schema.org/draft-04/schema",
      "type": "array",
      "description" : "An internationalized string value, supporting one or more language translations.",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "lang": { "type": "string", "maxLength": 10, "description": "The language or locale in which the text is written." },
          "text": { "type": "string", "maxLength": 2000, "description": "The internationalized text value." }
        }
      }
    }
- tags: |
    {
      "id": "http://api.covisint.com/idm/schema/tag",
      "$schema": "http://json-schema.org/draft-04/schema",
      "type": "array",
      "description" : "The tags associated with a resource.  This array is read-only, and may be modified on the resource endpoint with the appropriate tagging APIs.",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "tagName": { "type": "string", "description": "The tag associated with a resource." }
        }
      }
    }
- token: |
    {
      "id" : "http://api.covisint.com/schema/token",
      "$schema" : "http://json-schema.org/draft-04/schema",
      "type" : "object",
      "description" : "Schema representing an OAuth access token issued to a subject via the OAuth grant.",
      "extends" : {
            "$ref" : "http://api.covisint.com/schema/resource#"
      },
      "properties" : {
        "access_token" : {
          "type" : "string",
          "description": "The access token string.",
          "required": true
        },
        "refresh_token" : {
          "type" : "string",
          "description": "The refresh token string.",
          "required": true
        },
        "expires_in" : {
          "type" : "integer",
          "description": "The access token lifetime, in seconds.",
          "required": true
        },
        "scope" : {
          "type": "string",
          "description": "The scope of the access token. Multiple scopes are separated by spaces.",
          "required": true
        },
        "state" : {
          "type" : "string",
          "description": "A client-generated, opaque value used to maintain state and/or trust between the client and authorization server.",
          "required": false
        },
        "token_type" : {
          "type" : "string",
          "description": "The type of the token. Currently only Bearer tokens are supported.",
          "required": true
        }
      }
    }
- introspect: |
    {
      "id" : "http://api.covisint.com/schema/token",
      "$schema" : "http://json-schema.org/draft-04/schema",
      "type" : "object",
      "description" : "Schema representing the token information response.",
      "extends" : {
            "$ref" : "http://api.covisint.com/schema/resource#"
      },
      "properties" : {
        "active" : {
          "type" : "boolean",
          "description": "Flag indicating whether the token is valid. If the token is invalid (false) then this is will be the only attribute in the response.",
          "required": true
        },
        "scope" : {
          "type": "string",
          "description": "The scope of the access token. Multiple scopes will be separated by spaces.",
          "required": false
        },
        "iat" : {
          "type": "integer",
          "description": "Timestamp, measured in seconds, indicating when the token was issued.",
          "required": false
        },
        "exp" : {
          "type": "integer",
          "description": "Timestamp, measured in seconds, indicating when the token will expire.",
          "required": false
        },
        "sub" : {
          "type": "string",
          "description": "The subject of the token. This will either represent a person or an application",
          "required": false
        },
        "user" : {
          "type": "string",
          "description": "The identifier for the user who authorized this token. This will correspond to the Person ID of the person for which the token is issued. This attribute will not be included for an application-level token obtained through the client credentials flow.",
          "required": false
        },
        "client_id" : {
          "type": "string",
          "description": "The identifier for the client the token was issued to.",
          "required": false
        },
        "grant_type" : {
          "type": "string",
          "description": "The grant_type used for generating this token.",
          "enum": [ "authorization_code", "client_credentials", "password", "refresh_token" ],
          "required": false
        },
        "token_type" : {
          "type" : "string",
          "description": "The type of the token.",
          "enum": [ "Bearer" ],
          "required": false
        }
      }
    }
- oauthv2error: |
    {
      "id" : "http://api.covisint.com/schema/token",
      "$schema" : "http://json-schema.org/draft-04/schema",
      "type" : "object",
      "description" : "Schema representing the token information response, as per RFC6749, Section 5.2",
      "extends" : {
            "$ref" : "http://api.covisint.com/schema/resource#"
      },
      "properties" : {
        "error" : {
          "type" : "string",
          "description": "Error code.",
          "enum": [ "invalid_client", "invalid_request", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "unsupported_token_type" ],
          "required": true
        },
        "error_description" : {
          "type": "string",
          "description": "Additional information about the error.",
          "required": false
        }
      }
    }
traits:
- secured:
    usage: Apply this to any method that needs to be secured by a bearer token.
    description: Requests requires authentication using a bearer token.
    headers:
      Authorization:
        description: Access (bearer) token that is obtained from the /token endpoint
          of the oauth API.
        pattern: "^Bearer .*$"
        example: Bearer ZCtYUGpYRXpET0JvVE1rZzlWV3I1Yk
        required: true
    responses:
      401:
        description: |
          Authentication error. This is returned if the bearer token is not provided or is not valid.
        body:
          application/json:
            schema: oauthv2error
            example: |
              {
                "error": "invalid_client"
              }
      403:
        description: |
          Authorization error. This is returned if the requestor is not authorized to make the request.
        body:
          application/json:
            schema: oauthv2error
            example: |
              {
                "error": "unauthorized_client"
              }
"/authorization":
  description: Authorization endpoint
  get:
    description: |
      Get an OAuth 2.0 authorization.  A successful call will result in a redirection to the authorization server in order to receive the resource owner's consent.  The redirection will be to the login page or directly to the consent page (if the user is already authenticated and login is not forced).  Once consent is granted then the authorization server will send the user agent to the redirect_uri with query parameters state, scope, and code.
    queryParameters:
      client_id:
        description: The client identifier provided during client application onboarding.
        example: Pl6FScdRhgpUbwyB60FYHebShl57Y8Tp
        type: string
        required: true
      redirect_uri:
        description: The location the user should be returned to after the user authorizes
          the access.  This must match the URI registered with the application.  Included
          query parameters will not be compared with the registered URI and will returned
          in any callbacks.
        type: string
        required: false
      response_type:
        description: |
          Response type.  The allowed values are:
            + __code__: Indicates that an authorization code is being requested
            + __token__: Indicates that an implicit grant is being requested
        type: string
        example: code
        enum:
        - code
        - token
        required: true
      scope:
        description: |
          The space-delimited authorization scope(s) being requested.
        type: string
        required: true
      state:
        description: |
          A unique value submitted by the client to store state information and/or prevent cross-site request forgery attacks.  The value should be a unique string that is kept secret in the client.  It will be returned with the authorization code to the redirect URI and should be verified by the client.
        type: string
        required: false
      force_login:
        description: |-
          Whether or not to force a login. If false then the redirection will
          be to the consent page if a user is already authenticated with the
          authorization server.
        type: boolean
        required: false
        default: false
    responses:
      302:
        description: |
          Redirection to the authorization server for the resource owner's consent.
      401:
        description: |
          Authentication error. This is returned if the client ID is not valid.
        body:
          application/json:
            schema: oauthv2error
            example: |
              {
                "error": "invalid_client"
              }
"/token":
  description: Collection endpoint for token resources.
  get:
    is:
    - secured
    description: Search for refresh tokens associated to a user/person. A user ID/person
      ID is required. The response is an array of refresh tokens. The user_id and
      client_id query params are passed as search keys. It would return an array of
      one refresh token for a possible user_id and client_id combination. If only
      user_id is passed as an query param, then, all refresh tokens for the particular
      user are returned.
    headers:
      Accept:
        description: Media type.
        example: application/json
        type: string
        required: false
    queryParameters:
      user_id:
        description: The user id (Person ID) of the user (person) to use in the search.  Only
          refresh tokens for the given user (person) will be returned.
        type: string
        required: true
      client_id:
        description: The client_id to find.
        type: string
        required: false
      token_type:
        description: type of the token to be searched.  The currently supported value
          is refresh_token.
        type: string
        required: true
        enum:
        - refresh_token
    responses:
      200:
        description: |
          Successfully returned a collection of refresh token for a user_id and client_id.
        body:
          application/json:
            schema: token
            example: |
              [{
                "refresh_token": "2|F5GetywXY4yPYOgPVdJtCyTYIXh1H9Vc",
                "refresh_token_status": "approved",
                "refresh_token_issued_at": 1438264065268,
                "refresh_token_expires_in": 15551995,
                "user": "JL7M4G67",
                "client_id": "r7KCo6Rb2rXzDHYGaxvkvIi1tkAryk3Mc",
                "realm": "S-APIS-ONE",
                "scope": "email"
                }]
      400:
        description: "Bad request. \n"
        body:
          application/json:
            schema: oauthv2error
            example: |
              {
                "error": "unsupported_token_type",
                "error_description": "Token type must be refresh_token."
              }
  post:
    securedBy:
    - basic
    description: |
      Create or refresh access token. The generated token can be used for bearer-type authentication in other API calls.  The client id and client secret are passed in a basic Authorization header (username=client id and password=client secret). The grant type must always be passed as a paramter.  The other parameters that need to be passed are dictated by the grant type:
        +  **authorization_code**: grant_type, redirect_uri, code
        +  **password**: grant_type, scope, username or user_id, password
        +  **client_credentials**: grant_type, scope
        +  **refresh_token**: refresh_token, scope
    headers:
      Authorization:
        description: Basic authorization, using the client id and client secret issued
          during client provisioning.  To use the API console switch the Security
          Scheme to Basic Authentication and enter the client id in the Username field
          and client secret in the Password field.  This will set the Authorization
          header properly.
        pattern: "^Basic .*$"
        example: Basic aWQ6cGFzc3dvcmQ=
        required: true
    body:
      application/x-www-form-urlencoded:
        formParameters:
          grant_type:
            description: |
              The grant type.  Must be one of "authorization_code", "client_credentials", "refresh_token" or "password".
            type: string
            required: true
            example: client_credentials
          username:
            description: |
              The username of the resource owner (user).  This is the ID that the user uses to log in.  Either username or user_id is required when *grant_type* is "password". (An error will occur if both are supplied.) This is used in conjunction with password parameter to validate the resource owner's credentials. Will be ignored for any other grant type.
            type: string
            required: false
          user_id:
            description: |
              The person ID of the resource owner (user).  This is the unique identifier the system assigns to the user and is not the same as username--which is the ID that the user uses to log in.  Either user_id or username is required when *grant_type* is "password".  (An error will occur if both are supplied.) This is used in conjunction with password parameter to validate the resource owner's credentials. Will be ignored for any other grant type.
            type: string
            required: false
          password:
            description: |
              The resource owner password.  Required when *grant_type* is "password". This is used in conjunction with the username (or user_id) parameter to validate the resource owner's credentials. Will be ignored for any other grant type.
            type: string
            required: false
          code:
            description: |
              The authorization code that was issued by the authorization server as a result of a GET /authorization request.  Required when *grant_type* is "authorization_code". Will be ignored for any other grant type.
            type: string
            required: false
          redirect_uri:
            description: |
              The redirect URI.  Required when *grant_type* is "authorization_code". This is verified against the redirect URI used when obtaining the authorization code.  Will be ignored for any other grant type.
            type: string
            required: false
          scope:
            description: "The space-delimited authorization scope(s) being requested. \ This is applicable when *grant_type* is \"client_credentials\", \"password\", or \"refresh_token\". Will be ignored for any other grant type.     \nNote--For the authorization code grant type the scope is dictated by the scope value in the /authorization call.     \nNote--For refresh_token, the scope list must not include a scope not originally granted by the resource owner.\n"
            type: string
            required: false
          refresh_token:
            description: |
              The refresh token returned by a previous "authorization_code", "client_credentials" or "password" call.  Required when *grant_type* is "refresh_token".  Will be ignored for any other grant type.
            type: string
            required: false
    responses:
      200:
        description: |
          Successfully created and returned token. This token is used in a Bearer-type Authorization header for authentication to all other API calls.
        body:
          application/json:
            schema: token
            example: |
              {
                "access_token": "1/Ty5O27GtaDqeQBNTYy4NnIYlbKDF",
                "refresh_token": "1/kj5ihkwzGxoz4tQQGyFHeyKdgE1ZrPXe",
                "expires_in": 900,
                "scope": "email",
                "token_type": "Bearer"
              }
      400:
        description: |
          Bad request. This is returned if there is an issue with the request that does not involve client authentication.  The error response format is defined in [RFC6749, Section 5.2](https://tools.ietf.org/html/rfc6749#section-5.2).
        body:
          application/json:
            schema: oauthv2error
            example: |
              {
                "error": "unsupported_grant_type",
                "error_description": "Grant type must be one of: authorization_code, client_credentials, refresh_token or password.
              }
      401:
        description: |
          Invalid client authentication. This is returned if the client ID/client secret combination used in the Basic Authentication header is not valid.  The error response format is defined in [RFC6749, Section 5.2](https://tools.ietf.org/html/rfc6749#section-5.2).
        body:
          application/json:
            schema: oauthv2error
            example: |
              {
                "error": "invalid_request",
                "error_description": "Invalid request credentials"
              }
"/revoke":
  is:
  - secured
  description: Endpoint for token revocation operation.
  post:
    description: "Revoke an access or refresh token. This endpoint accepts a token in the body.\n  + If access token is passed, only access token will be revoked and refresh token will continue to exist and will be valid\n  + If refresh token is passed, both access token and refresh token will be revoked \n"
    body:
      application/x-www-form-urlencoded:
        formParameters:
          token:
            description: Access or refresh token to revoke
            type: string
            required: true
          token_type_hint:
            description: |
              A hint about the type of token being submitted for revocation. This may improve the performance of the server and is not required to be provided or correct.
            type: string
            required: false
            enum:
            - access_token
            - refresh_token
            example: access_token
          cascade:
            description: Whether or not to cascade the revocation to the associated
              access or refresh token.  If the passed token is an access token, then
              this indicates whether all access tokens associated with the refresh
              token should also be revoked.  If the passed token is a refresh token,
              then this indicates whether the refresh token associated with the access
              token (if it exists) should also be revoked.
            type: boolean
            required: true
    responses:
      200:
        description: Successfully ensured that the token is not valid.  This may be
          a result of a successfully revoked token or the submitted token was not
          valid.
"/introspect":
  is:
  - secured
  securedBy:
  - basic
  description: Endpoint for token information operations.
  post:
    description: Returns whether or not an access or refresh token is active.  If
      it is active then additional information about the token is also provided.
    headers:
      Accept:
        description: Media type.
        example: application/json
        type: string
        required: false
    body:
      application/x-www-form-urlencoded:
        formParameters:
          token:
            description: Access or refresh token for introspection.
            type: string
            required: true
          token_type_hint:
            description: |
              A hint about the type of token being submitted for introspection. This may improve the performance of the server and is not required to be provided or correct.
            type: string
            required: false
            enum:
            - access_token
            - refresh_token
            example: access_token
    responses:
      200:
        description: Successfully processed request.  The response contains whether
          the token is active or not.  If active, additional information about the
          token is also returned.
        body:
          application/json:
            schema: introspect
            example: |
              If the token type is access_token and  is active,
              {
                "active": "true",
                "scope": "email",
                "iat": 1427954154425,
                "exp": 1427966158455,
                "sub": "{person}Y6U9JL4",
                "user": "Y6U9JL4",
                "client_id": "GbvgMuQTF8Hw1lgFNGFPiaTOrA3H",
                "grant_type": "authorization_code",
                "token_type": "Bearer"
              }
              If the token type is refresh_token and  is active,
              {
                "refresh_token": "2|GbvgMuQTF8Hw1lgFNGFPiaTOrA3H",
                "refresh_token_status": "approved",
                "refresh_token_issued_at": 1436424622720,
                "refresh_token_expires_in": 0,
                "user": "COVS_ADMIN",
                "client_id": "GbvgMuQTF8Hw1lgFNGFPiaTOrA3H",
                "realm": "COVSINT",
                "scope": "all"
              }
              If the token is invalid or inactive:
              {
                "active": "false"
              }