openapi: 3.0.1
info:
  title: NPR Identity Service
  description: The entry point to user-specific information
  termsOfService: https://dev.npr.org/guide/prerequisites/terms-of-use
  contact:
    name: NPR One Enterprise Team
    url: https://dev.npr.org
    email: NPROneEnterprise@npr.org
  version: "2"
externalDocs:
  description: Learn more at the NPR One Developer Center
  url: https://dev.npr.org/guide/services/identity
servers:
  - url: https://identity.api.npr.org/
paths:
  /v2/token:
    post:
      tags:
        - Authorization
      summary: NPR Create a new OAuth2 access token
      description: |-
        Please be aware that the required parameters are contingent on the `grant_type` that you select.

        For the `authorization_code` grant type, you are **required** to pass in the `code` and `redirect_uri` parameters.

        For the `client_credentials` grant type, you do not need to pass in any additional parameters beyond the basic requirements. `code` and `redirect_uri` parameters will be ignored.

        For the `device_code` grant type, you are **required** to pass in the `code` parameter. If you are a third-party developer, you are also required to provide the `scope` parameter; see the documentation for `GET /v2/authorize` for possible values. `redirect_uri` parameter will be ignored.

        For the `refresh_token` grant type, you are **required** to pass in the `refresh_token` parameter. The `scope` parameter can optionally be used to request a different set of scopes than were used in the original request, but it **cannot** contain any scopes that were not previously requested. If not specified, then `scope` will be set to whichever scopes were used for the original access token request. If trading in an old non-expiring access token for a refresh-enabled token, set the value of `refresh_token` to the access token value and `token_type_hint` must be set to `access_token`. `code` and `redirect_uri` parameters will be ignored.

        The `anonymous_user` grant type is a custom grant type created by NPR to suit our needs for functionality such as our "try-before-you-buy" experience. If you are a third-party developer, you will not have access to this grant type unless we have explicitly given you permission within our system.
        For this grant type, if you are a third-party developer, you are required to provide the `scope` parameter; see the documentation for `GET /v2/authorize` for possible values. `code` and `redirect_uri` parameters will be ignored.

        If you are unsure of which grant type to select, assume that `authorization_code` is the one you want.

        Note that at this time, refresh tokens are an opt-in feature; however, in the future, they will gradually transition to being opt-out, and ultimately required for all clients. Our general guidance at this time is that if this endpoint starts returning refresh tokens for you, you are responsible for implementing the code to handle them appropriately in accordance with the OAuth 2.0 spec. For more information about our gradual rollout of this feature, please contact the NPR One API team.
      operationId: createToken
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - client_id
                - client_secret
                - grant_type
              type: object
              properties:
                grant_type:
                  type: string
                  description: The type of grant the client is requesting
                  enum:
                    - authorization_code
                    - client_credentials
                    - device_code
                    - refresh_token
                    - anonymous_user
                client_id:
                  type: string
                  description: "The client's ID, required for all grant types."
                client_secret:
                  type: string
                  description: "The client's secret, required for all grant types."
                code:
                  type: string
                  description: "Required for `authorization_code` and `device_code` grant types. The authorization code from a successful call to `/v2/authorize`, or a device code from a successful call to `/v2/device`."
                redirect_uri:
                  type: string
                  description: Required for `authorization_code` grant type. The requested redirect_uri.
                refresh_token:
                  type: string
                  description: Required for `refresh_token` grant type. A valid refresh token from a previous successful call to `POST /v2/token`.
                scope:
                  type: string
                  description: Required for third-party developers using the `device_code` grant types. Optionally used by the `refresh_token` grant type. A space-separated list of scope(s) requested by the application.
                token_type_hint:
                  type: string
                  description: "A hint about the type of the token submitted for a new access and refresh token. If unspecified, the default value is assumed to be `refresh_token`."
                  enum:
                    - access_token
                    - refresh_token
        required: true
      responses:
        "200":
          description: A new token was successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenData'
        "400":
          description: "A bad request; generally, one or more parameters passed in were incorrect or missing"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        "401":
          description: "The client credentials were invalid (any grant type), the user has not yet logged in or has purposely denied the request (`device_code` grant type), or the authorization server denied the request."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        "500":
          description: A server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        "503":
          description: The system is undergoing maintenance and we are unable to fulfill this request. Look for a `Retry-After` header to see the predicted time the system will be back up.
          headers:
            Retry-After:
              description: The predicted time the system will be back up
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
  /v2/authorize:
    get:
      tags:
        - Authorization
      summary: NPR Show a web-based login/signup form to a user
      description: |-
        If the parameters passed to this endpoint are correct, it will redirect to `npr.org/oauth2/login` for the user to complete the sign-in.

        Currently acceptable values for `scope` are any combination of the following:
        - `identity.readonly` - for read-only access to the Identity Service
        - `identity.write` - for write access to the Identity Service
        - `listening.readonly` - for read-only access to the Listening Service
        - `listening.write` - for write access to the Listening Service
        - `localactivation` - for all access to the Local Activation Service

        It is generally suggested that you assume that you will need all of the current scopes in order to successfully implement an NPR One application.

        If the parameters passed in are NOT correct and the client passed in a valid `redirect_uri` parameter, the request will be redirected to `{{YOUR_REDIRECT_URI}}?error={{ERROR_TYPE}}&message={{ERROR_DESCRIPTION}}`.
        If the parameters passed are NOT correct and the client did not pass in a valid `redirect_uri` parameter, this endpoint will return the errors encoded as JSON objects (along with the corresponding HTTP status code -- usually 400).
        The latter is intended for development and debugging purposes -- in a real-world situation, errors returned as JSON objects are irretrievable by the client application, and thus passing in a valid `redirect_uri` is critical even for the purpose of capturing errors.

        If the user successfully logs in and authorizes the application, the request will be redirected to `{{YOUR_REDIRECT_URI}}?code={{AUTHORIZATION_CODE}}&state={{CSRF_TOKEN}}`

        If the user DENIES the application, they will be redirected to `{{YOUR_REDIRECT_URI}}?error=denied&message=The%20user%20has%20denied%20the%20login%20and%20access%20request&state={{CSRF_TOKEN}}`.
        This means that if your application flow requires a user to log in in order to proceed, it is up to you to give them the proper messaging explaining that the sign-in must be authorized in order to continue.

        Finally, please do not confuse an authorization code with an access token. Once your app has completed this flow, you will still need to call `POST /v2/token` in order to swap the code for a valid access token.
      operationId: getAuthorizationPage
      parameters:
        - name: client_id
          in: query
          description: The client's ID
          required: true
          schema:
            type: string
        - name: redirect_uri
          in: query
          description: The client's URL to redirect to if the authentication is approved
          required: true
          schema:
            type: string
        - name: response_type
          in: query
          description: "The type of response; currently, only `code` is supported"
          required: true
          schema:
            type: string
            enum:
              - code
        - name: scope
          in: query
          description: A space-separated list of scope(s) requested by the application
          required: true
          schema:
            type: string
        - name: email
          in: query
          description: An email address to prepopulate on the login screen
          schema:
            type: string
        - name: state
          in: query
          description: "A CSRF token generated by the client, to be roundtripped through the request for added security"
          required: true
          schema:
            type: string
        - name: prompt
          in: query
          description: Optional prompt parameter to be passed to Akamai /login/authorize
          schema:
            type: string
            enum:
              - login
      responses:
        "302":
          description: "The correct parameters were passed in and we are redirecting to the authentication page; OR, a valid `redirect_uri` was supplied but there was another error, and the error type and message are embedded in the querystring."
          headers:
            Location:
              description: The sign-in page to redirect to; most clients will process this redirect automatically.
              schema:
                type: string
                format: url
          content: {}
        "400":
          description: "A bad request; generally, one or more parameters passed in were incorrect or missing. This error will only be shown if the client did not pass in a valid `redirect_uri`; otherwise, all errors will be returned as 302s to the supplied `redirect_uri`, with the error type and message embedded in the querystring."
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/SimpleError'
        "401":
          description: "The client credentials were invalid (i.e., the `redirect_uri` does not match what we have stored for this client) or the authorization server denied the request. This error will only be shown if the client did not pass in a valid `redirect_uri`; otherwise, all errors will be returned as 302s to the supplied `redirect_uri`, with the error type and message embedded in the querystring."
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/SimpleError'
        "500":
          description: "There was an unspecified server error. This error will only be shown if the client did not pass in a valid `redirect_uri`; otherwise, all errors will be returned as 302s to the supplied `redirect_uri`, with the error type and message embedded in the querystring."
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/SimpleError'
        "503":
          description: "The system is undergoing maintenance and we are unable to fulfill this request. This error will only be shown if the client did not pass in a valid `redirect_uri`; otherwise, all errors will be returned as 302s to the supplied `redirect_uri`, with the error type and message embedded in the querystring."
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/SimpleError'
  /v2/device:
    post:
      tags:
        - Authorization
      summary: NPR Initiate an OAuth2 login flow for limited input devices
      description: |-
        This flow should only be used by clients who cannot show a native webview or do not have advanced input controls. It is an alternative to `GET /v2/authorize`.

        Third-party clients will need to use one or the other of these two endpoints, but they will generally not use both.
      operationId: generateDeviceCode
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - client_id
                - client_secret
              type: object
              properties:
                client_id:
                  type: string
                  description: The client's ID
                client_secret:
                  type: string
                  description: The client's secret key
                scope:
                  type: string
                  description: A space-separated list of scope(s) requested by the application. Required for all untrusted clients; will be ignored for trusted clients.
        required: true
      responses:
        "201":
          description: "We have generated a unique device code and user code. These will only be valid for the amount of time specified in the `expires_in` field; if the user does not complete the login process in that amount of time, the client will need to request a new set of codes."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceCodeData'
        "400":
          description: "A bad request; generally, one or more parameters passed in were incorrect or missing"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        "401":
          description: The client credentials were invalid or the authorization server denied the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        "500":
          description: A server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        "503":
          description: The system is undergoing maintenance and we are unable to fulfill this request. Look for a `Retry-After` header to see the predicted time the system will be back up.
          headers:
            Retry-After:
              description: The predicted time the system will be back up
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
  /v2/token/revoke:
    post:
      tags:
        - Authorization
      summary: NPR Revoke an existing OAuth2 access token
      description: |-
        Our implementation follows the proposed IETF specification [RFC-7009](https://tools.ietf.org/html/rfc7009).

        If your client application offers the ability to for a logged-in user to log out, and you have access to a long-lived
        `client_credentials` token (i.e. you have generated one that you are storing securely for the lifetime of the entire app
        install), we suggest (but do not require) that you call this endpoint and revoke the access token belonging to the
        logged-in user as part of your logout process. If you do not already have a long-lived `client_credentials` token,
        please don't generate one just for the purposes of calling this endpoint.

        If you are building a prototype application, we also recommend that you use this endpoint to clean up access tokens
        that you generate during the testing of your app and do not intend to reuse.

        Note that revoking an access token will automatically revoke any refresh tokens associated with it, and vice-versa.
      operationId: revokeToken
      parameters:
        - name: Authorization
          in: header
          description: "A `client_credentials` access token from the same client application as the token being revoked. Should start with `Bearer`, followed by a space, followed by the token."
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - token
              type: object
              properties:
                token:
                  type: string
                  description: The access token or refresh token that the client wants to have revoked.
                token_type_hint:
                  type: string
                  description: "A hint about the type of the token submitted for revocation. If unspecified, the default value is assumed to be `access_token`."
                  enum:
                    - access_token
                    - refresh_token
        required: true
      responses:
        "200":
          description: The old token was successfully revoked
          content:
            application/json:
              schema:
                type: object
                description: An empty JSON object
        "400":
          description: "A bad request; generally, one or more parameters passed in were incorrect or missing"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        "401":
          description: The client credentials were invalid or the authorization server denied the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        "403":
          description: The client associated with the access token in the header does not own the access token that this request is attempting to revoke.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        "500":
          description: A server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        "503":
          description: The system is undergoing maintenance and we are unable to fulfill this request. Look for a `Retry-After` header to see the predicted time the system will be back up.
          headers:
            Retry-After:
              description: The predicted time the system will be back up
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
  /v2/user:
    get:
      tags:
        - Identity
      summary: NPR Get the latest state information about the logged-in user
      description: "After a successful login, the client should send a `GET` call approximately once an hour to refresh the user data."
      operationId: getUser
      parameters:
        - name: Authorization
          in: header
          description: "Your access token from the Authorization Service. Should start with `Bearer`, followed by a space, followed by the token."
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The request was successful
          headers:
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              schema:
                type: integer
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/UserDocument'
        "401":
          description: The client is not authorized to complete this request. Check to ensure a valid access token was passed in the headers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        "429":
          description: "The client has exceeded the number of daily calls as per their rate limit. For now, this only applies to prototype applications and untrusted clients. Trusted clients will never be rate-limited, nor will any production apps."
          headers:
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              schema:
                type: integer
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        "500":
          description: A server error
          headers:
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              schema:
                type: integer
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        "503":
          description: The system is undergoing maintenance and we are unable to fulfill this request. Look for a `Retry-After` header to see the predicted time the system will be back up.
          headers:
            Retry-After:
              description: The predicted time the system will be back up
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
      security:
        - oauth2:
            - identity.readonly
    delete:
      tags:
        - Identity
      summary: NPR Delete the user's account
      description: "Use with caution as some steps are irreverisble. Initiates the user account deletion process, including removal of all user PII and account access."
      operationId: deleteUser
      parameters:
        - name: Authorization
          in: header
          description: "Your access token from the Authorization Service. Should start with `Bearer`, followed by a space, followed by the token."
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The request was successful
          headers:
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              schema:
                type: integer
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/UserDocument'
        "401":
          description: The client is not authorized to complete this request. Check to ensure a valid access token was passed in the headers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        "500":
          description: A server error
          headers:
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              schema:
                type: integer
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        "503":
          description: The system is undergoing maintenance and we are unable to fulfill this request. Look for a `Retry-After` header to see the predicted time the system will be back up.
          headers:
            Retry-After:
              description: The predicted time the system will be back up
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
      security:
        - oauth2:
            - identity.write
  /v2/stations:
    put:
      tags:
        - Identity
      summary: NPR Update the logged-in user's favorite station(s)
      description: "Right now, only the primary station can be changed. Previously selected stations will not be deleted, but the new station will be moved to first in the array."
      operationId: updateStations
      parameters:
        - name: Authorization
          in: header
          description: "Your access token from the Authorization Service. Should start with `Bearer`, followed by a space, followed by the token."
          required: true
          schema:
            type: string
      requestBody:
        description: A JSON-serialized array of station IDs
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
          application/vnd.collection.doc+json:
            schema:
              type: array
              items:
                type: integer
        required: false
      responses:
        "201":
          description: The request was successful
          headers:
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              schema:
                type: integer
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/UserDocument'
        "400":
          description: "A bad request; generally, one or more parameters passed in were incorrect or missing"
          headers:
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              schema:
                type: integer
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        "401":
          description: The client is not authorized to complete this request. Check to ensure a valid access token was passed in the headers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        "429":
          description: "The client has exceeded the number of daily calls as per their rate limit. For now, this only applies to prototype applications and untrusted clients. Trusted clients will never be rate-limited, nor will any production apps."
          headers:
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              schema:
                type: integer
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        "500":
          description: A server error
          headers:
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              schema:
                type: integer
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        "503":
          description: The system is undergoing maintenance and we are unable to fulfill this request. Look for a `Retry-After` header to see the predicted time the system will be back up.
          headers:
            Retry-After:
              description: The predicted time the system will be back up
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
      security:
        - oauth2:
            - identity.write
      x-codegen-request-body-name: body
  /v2/following:
    post:
      tags:
        - Identity
      summary: NPR Update the following status of the logged-in user for a particular aggregation
      description: "After a successful call, this returns a User document with an updated list of affiliations."
      operationId: postFollowing
      parameters:
        - name: Authorization
          in: header
          description: "Your access token from the Authorization Service. Should start with `Bearer`, followed by a space, followed by the token."
          required: true
          schema:
            type: string
      requestBody:
        description: "A JSON-serialized object which contains data about a user affiliation such as the aggregation ID, affiliation rating, aggregation URL, days since last listen, and following status."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Affiliation'
        required: true
      responses:
        "201":
          description: The request was successful
          headers:
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              schema:
                type: integer
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/UserDocument'
        "400":
          description: "A bad request; generally, one or more parameters passed in were incorrect or missing"
          headers:
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              schema:
                type: integer
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        "401":
          description: The client is not authorized to complete this request. Check to ensure a valid access token was passed in the headers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        "429":
          description: "The client has exceeded the number of daily calls as per their rate limit. For now, this only applies to prototype applications and untrusted clients. Trusted clients will never be rate-limited, nor will any production apps."
          headers:
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              schema:
                type: integer
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        "500":
          description: A server error
          headers:
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds left in the current period
              schema:
                type: integer
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        "503":
          description: The system is undergoing maintenance and we are unable to fulfill this request. Look for a `Retry-After` header to see the predicted time the system will be back up.
          headers:
            Retry-After:
              description: The predicted time the system will be back up
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
            application/vnd.collection.doc+json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
      security:
        - oauth2:
            - identity.write
      x-codegen-request-body-name: body
components:
  schemas:
    SimpleError:
      required:
        - message
        - type
      type: object
      properties:
        message:
          type: string
          description: A message describing the error that occurred
        type:
          type: string
          description: A short string representing the type of error that occurred
          default: error
      description: "A simple representation of an error result from an API call, rarely used; in most cases we still return a Collection.doc+JSON document for errors"
    AccessTokenData:
      required:
        - access_token
        - expires_in
        - token_type
      type: object
      properties:
        access_token:
          type: string
          description: The access token to use for all future calls
        token_type:
          type: string
          description: "Identifies the type of token returned. At this time, this field always has the value `Bearer`."
          enum:
            - Bearer
            - MAC
        expires_in:
          type: integer
          description: The remaining lifetime of the access token (in seconds)
          format: int32
        refresh_token:
          type: string
          description: "The refresh token that can be used to obtain a new access token if the old one expires; if a refresh token is returned, it is the client's responsibility to securely cache it for future use."
    DeviceCodeData:
      required:
        - device_code
        - expires_in
        - interval
        - user_code
        - verification_uri
      type: object
      properties:
        device_code:
          type: string
          description: "40-character code for the device to input into the /token endpoint, not for display to the user"
        user_code:
          type: string
          description: "6-character alphanumeric code for the user to enter at https://npr.org/device, to be displayed by the client application"
        verification_uri:
          type: string
          description: "The URL where the user should input their code, to be displayed by the client application"
          default: https://npr.org/device
        expires_in:
          type: integer
          description: "The number of seconds for which this set of codes will be valid, after which they will be purged"
          format: int32
          default: 1800
        interval:
          type: integer
          description: The number of seconds the client application should maintain between requests to the /token endpoint
          format: int32
          default: 5
    Error:
      required:
        - code
      type: object
      properties:
        code:
          type: integer
          description: The error code
          format: int32
        text:
          type: string
          description: The error description
        debug:
          type: string
          description: Additional debug information if debug mode is turned on
      description: A serialized version of any error encountered when processing this request
    CollectionDocument:
      required:
        - attributes
        - errors
        - href
        - items
        - links
        - version
      type: object
      properties:
        version:
          type: string
          description: The version of the Collection.Doc+JSON spec being used
          default: "1.0"
        href:
          type: string
          description: A URL representation of the resource; should generally be ignored by clients unless noted otherwise
        attributes:
          type: object
          properties: {}
        items:
          type: array
          items:
            type: object
            properties: {}
        links:
          type: object
          properties: {}
        errors:
          type: array
          description: "A list of encountered errors, ignored on POST, PUT"
          items:
            type: object
            properties: {}
      description: Base Collection.Doc+JSON output
    ErrorDocument:
      description: A Collection.doc+JSON representation of an error result from an API call
      allOf:
        - $ref: '#/components/schemas/CollectionDocument'
        - type: object
          properties:
            attributes:
              type: object
              properties: {}
              description: Ignore; will be empty for errors
            items:
              type: array
              description: Ignore; will be empty for errors
              items:
                type: object
                properties: {}
            links:
              type: object
              properties: {}
              description: Ignore; will be empty for errors
            errors:
              type: array
              description: "A list of encountered errors, ignored on POST, PUT"
              items:
                $ref: '#/components/schemas/Error'
    AbstractLink:
      required:
        - href
      type: object
      properties:
        href:
          type: string
          description: The link to be followed
          format: uri
    AbstractCDocLink:
      allOf:
        - $ref: '#/components/schemas/AbstractLink'
        - required:
            - content-type
          type: object
          properties:
            content-type:
              type: string
              description: The MIME type of the response of this link
    Affiliation:
      required:
        - following
        - href
        - id
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for the aggregation (program)
        title:
          type: string
          description: The title for the aggregation (program)
        rating:
          type: number
          description: The user's average rating for this affiliation on a scale of 0-1. Absent if user never listened to the aggregation.
          format: float
        href:
          type: string
          description: A link to more details about the program from the NPR Story API
        daysSinceLastListen:
          type: integer
          description: The number of days since a user last listened to a story from this aggregation. Absent if user never listened to the aggregation.
          format: int32
        notif_following:
          type: array
          description: The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about the podcasts they follow.
          items:
            type: string
        notif_rated:
          type: array
          description: The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about the podcasts they have highly rated.
          items:
            type: string
        following:
          type: boolean
          description: "Whether or not the user is following the aggregation. When changing affiliation status, the client is expected to toggle this value and then send the entire object back."
          default: false
      description: A program (aggregation) that a given user has shown an affiliation with
    UserDocument:
      allOf:
        - $ref: '#/components/schemas/CollectionDocument'
        - type: object
          properties:
            items:
              type: array
              description: "Not used, ignored on a PUT"
              items:
                type: object
                properties: {}
            links:
              type: object
              properties: {}
              description: "A list of links, not used by the Identity Service; ignored on a PUT"
            attributes:
              $ref: '#/components/schemas/UserData'
    UserData:
      required:
        - algolia
        - cohort
        - id
        - organizations
      type: object
      properties:
        id:
          type: string
          description: Some unique identifier for the user
        firstName:
          type: string
          description: The user's first name
        lastName:
          type: string
          description: The user's last name
        email:
          type: string
          description: The user's email address
        cohort:
          $ref: '#/components/schemas/Cohort'
        organizations:
          type: array
          description: User's chosen NPR Member Station(s)
          items:
            $ref: '#/components/schemas/Organization'
        affiliations:
          type: array
          description: Program(s) that the user has positively interacted with
          items:
            $ref: '#/components/schemas/Affiliation'
        algolia:
          type: array
          description: Use this information to search Algolia for stories
          items:
            $ref: '#/components/schemas/Algolia'
        totalListeningTime:
          type: string
          description: Internal use only. User's total listening time across all platforms.
      description: Object; see description of a user object below
    Cohort:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: string
          description: A short ID for this cohort; ignored on a PUT
        name:
          type: string
          description: "A text string identifying the cohort, useful for metrics; ignored on a PUT"
        public:
          type: string
          description: For internal use only; represents the current configuration file being used by the Listening Service
        test:
          type: string
          description: For internal use only; represents the test configuration file being used by the Listening Service
      description: An experimental grouping for User Experience A/B Testing
    Organization:
      required:
        - call
        - city
        - displayName
        - id
      type: object
      properties:
        id:
          type: string
          description: Some unique identifier for the organization for the user
        serviceId:
          type: string
          description: "Some unique identifier for the user's organization's primary service, or null if the org has no services"
        displayName:
          type: string
          description: "A short displayable text field for the end user, strictly text; ignored on PUT"
        call:
          type: string
          description: Station call letters
        city:
          type: string
          description: A short description of the station's main market city
        logo:
          type: string
          description: Station logo image url
        smallLogo:
          type: string
          description: Station logo image url
        donationUrl:
          type: string
          description: Station donation page URL
        notif_org:
          type: array
          description: The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about their localized station.
          items:
            type: string
      description: A station that a user has an affiliation with
    Algolia:
      required:
        - apiKey
      type: object
      properties:
        apiKey:
          type: string
          description: A search API key for this user
      description: Parameters for querying the Algolia Search SDK for content
  responses:
    Simple400:
      description: "A bad request; generally, one or more parameters passed in were incorrect or missing"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
        application/vnd.collection.doc+json:
          schema:
            $ref: '#/components/schemas/SimpleError'
    Simple401:
      description: The client credentials were invalid or the authorization server denied the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
        application/vnd.collection.doc+json:
          schema:
            $ref: '#/components/schemas/SimpleError'
    Simple500:
      description: A server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
        application/vnd.collection.doc+json:
          schema:
            $ref: '#/components/schemas/SimpleError'
    Simple503:
      description: The system is undergoing maintenance and we are unable to fulfill this request. Look for a `Retry-After` header to see the predicted time the system will be back up.
      headers:
        Retry-After:
          description: The predicted time the system will be back up
          schema:
            type: string
            format: date-time
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
        application/vnd.collection.doc+json:
          schema:
            $ref: '#/components/schemas/SimpleError'
    IdentitySuccess:
      description: The request was successful
      headers:
        X-RateLimit-Remaining:
          description: The number of remaining requests in the current period
          schema:
            type: integer
        X-RateLimit-Reset:
          description: The number of seconds left in the current period
          schema:
            type: integer
        X-RateLimit-Limit:
          description: The number of allowed requests in the current period
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserDocument'
        application/vnd.collection.doc+json:
          schema:
            $ref: '#/components/schemas/UserDocument'
    "400WithDocument":
      description: "A bad request; generally, one or more parameters passed in were incorrect or missing"
      headers:
        X-RateLimit-Remaining:
          description: The number of remaining requests in the current period
          schema:
            type: integer
        X-RateLimit-Reset:
          description: The number of seconds left in the current period
          schema:
            type: integer
        X-RateLimit-Limit:
          description: The number of allowed requests in the current period
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorDocument'
        application/vnd.collection.doc+json:
          schema:
            $ref: '#/components/schemas/ErrorDocument'
    "401WithDocument":
      description: The client is not authorized to complete this request. Check to ensure a valid access token was passed in the headers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorDocument'
        application/vnd.collection.doc+json:
          schema:
            $ref: '#/components/schemas/ErrorDocument'
    "404WithDocument":
      description: "The resource with the requested ID could not be found, and the server was unable to complete the request."
      headers:
        X-RateLimit-Remaining:
          description: The number of remaining requests in the current period
          schema:
            type: integer
        X-RateLimit-Reset:
          description: The number of seconds left in the current period
          schema:
            type: integer
        X-RateLimit-Limit:
          description: The number of allowed requests in the current period
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorDocument'
        application/vnd.collection.doc+json:
          schema:
            $ref: '#/components/schemas/ErrorDocument'
    "429WithDocument":
      description: "The client has exceeded the number of daily calls as per their rate limit. For now, this only applies to prototype applications and untrusted clients. Trusted clients will never be rate-limited, nor will any production apps."
      headers:
        X-RateLimit-Remaining:
          description: The number of remaining requests in the current period
          schema:
            type: integer
        X-RateLimit-Reset:
          description: The number of seconds left in the current period
          schema:
            type: integer
        X-RateLimit-Limit:
          description: The number of allowed requests in the current period
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorDocument'
        application/vnd.collection.doc+json:
          schema:
            $ref: '#/components/schemas/ErrorDocument'
    "500WithDocument":
      description: A server error
      headers:
        X-RateLimit-Remaining:
          description: The number of remaining requests in the current period
          schema:
            type: integer
        X-RateLimit-Reset:
          description: The number of seconds left in the current period
          schema:
            type: integer
        X-RateLimit-Limit:
          description: The number of allowed requests in the current period
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorDocument'
        application/vnd.collection.doc+json:
          schema:
            $ref: '#/components/schemas/ErrorDocument'
    "503WithDocument":
      description: The system is undergoing maintenance and we are unable to fulfill this request. Look for a `Retry-After` header to see the predicted time the system will be back up.
      headers:
        Retry-After:
          description: The predicted time the system will be back up
          schema:
            type: string
            format: date-time
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorDocument'
        application/vnd.collection.doc+json:
          schema:
            $ref: '#/components/schemas/ErrorDocument'
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: "Your access token from the Authorization Service. Should start with `Bearer`, followed by a space, followed by the token."
      required: true
      schema:
        type: string
    X-Advertising-ID:
      name: X-Advertising-ID
      in: header
      description: "A device-specific advertising identifier, if possible. Apple's IDFA is an example."
      schema:
        type: string
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://authorization.api.npr.org/v2/authorize
          tokenUrl: https://authorization.api.npr.org/v2/token
          scopes:
            identity.readonly: "See your personal information, such as your first name, last name, and favorite station."
            identity.write: "Update your personal information, such as your favorite station(s) or program(s) you follow, on your behalf."
            listening.readonly: See your NPR One listening history and get audio recommendations.
            listening.write: "Record that you have heard, marked as interesting, and/or skipped NPR One stories in order to personalize future audio recommendations."
            localactivation: Connect you with your local NPR member station for communication purposes.
tags:
  - name: Authorization
  - name: Identity