NPR Authorization API
The Authorization API from NPR — 4 operation(s) for authorization.
OpenAPI Specification
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