openapi: 3.0.1
info:
  title: NPR Identity Service Authorization 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: Authorization
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'
components:
  schemas:
    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
    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.
  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