openapi: 3.0.1
info:
  title: NPR Service Authorization Identity API
  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'
servers:
- url: https://identity.api.npr.org/
tags:
- name: Identity
paths:
  /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:
    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'
    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'
    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
    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
    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
    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
    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
    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
    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
  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.
externalDocs:
  description: Learn more at the NPR One Developer Center
  url: https://dev.npr.org/guide/services/identity