@datafire/npr_authorization v3.0.0

@datafire/npr_authorization

Client library for NPR Authorization Service

Installation and Usage

npm install --save @datafire/npr_authorization

let npr_authorization = require('@datafire/npr_authorization').create({
  access_token: "",
  refresh_token: "",
  client_id: "",
  client_secret: "",
  redirect_uri: ""
});

.then(data => {
  console.log(data);
});

Description

The interface to our OAuth2 server

Actions

oauthCallback

Exchange the code passed to your redirect URI for an access_token

npr_authorization.oauthCallback({
  "code": ""
}, context)

Input

• input object
  • code required string

Output

• output object
  • access_token string
  • refresh_token string
  • token_type string
  • scope string
  • expiration string

oauthRefresh

Exchange a refresh_token for an access_token

npr_authorization.oauthRefresh(null, context)

Input

This action has no parameters

Output

• output object
  • access_token string
  • refresh_token string
  • token_type string
  • scope string
  • expiration string

getAuthorizationPage

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.

npr_authorization.getAuthorizationPage({
  "client_id": "",
  "redirect_uri": "",
  "response_type": "",
  "scope": "",
  "state": ""
}, context)

Input

• input object
  • client_id required string: The client's ID
  • redirect_uri required string: The client's URL to redirect to if the authentication is approved
  • response_type required string (values: code): The type of response; currently, only code is supported
  • scope required string: A space-separated list of scope(s) requested by the application
  • email string: An email address to prepopulate on the login screen
  • state required string: A CSRF token generated by the client, to be roundtripped through the request for added security

Output

Output schema unknown

generateDeviceCode

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.

npr_authorization.generateDeviceCode({
  "client_id": "",
  "client_secret": ""
}, context)

Input

• input object
  • client_id required string: The client's ID
  • client_secret required string: The client's secret key
  • scope string: A space-separated list of scope(s) requested by the application. Required for all untrusted clients; will be ignored for trusted clients.

Output

• output DeviceCodeData

createToken

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. service, username and password parameters will be ignored.

For the client_credentials grant type, you do not need to pass in any additional parameters beyond the basic requirements. code, redirect_uri, service, username and password 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, service, username and password parameters will be ignored.

For the password grant type, you are required to pass in the username and password parameters. The code and redirect_uri parameters are ignored. Third-party developers do not have access to this grant type.

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, redirect_uri, service, username and password parameters will be ignored.

The temporary_user and anonymous_user grant types are custom grant types 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 these grant types unless we have explicitly given you permission within our system. For these grant types, 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, redirect_uri, service, username and password parameters will be ignored.

The third_party grant type is another custom grant type created by NPR to handle login via third-party providers such as Facebook and Google. If you are a third-party developer, you will not have access to this grant types unless we have explicitly given you permission within our system. For this grant type, you are required to pass in the service and token parameters. 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. The code and redirect_uri parameters are 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.

npr_authorization.createToken({
  "grant_type": "",
  "client_id": "",
  "client_secret": ""
}, context)

Input

• input object
  • grant_type required string (values: authorization_code, client_credentials, device_code, password, refresh_token, temporary_user, anonymous_user, third_party): The type of grant the client is requesting
  • client_id required string: The client's ID, required for all grant types.
  • client_secret required string: The client's secret, required for all grant types.
  • code string: 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 string: Required for authorization_code grant type. The requested redirect_uri.
  • username string: Required for password grant type. The email address of an NPR user.
  • password string: Required for password grant type. The password that matches the user specified with the username parameter.
  • service string (values: facebook, google, microsoft, janrain, comcast): Required for third_party grant type. The name of the third-party login provider.
  • refresh_token string: Required for refresh_token grant type. A valid refresh token from a previous successful call to POST /v2/token.
  • scope string: Required for third-party developers using the device_code, temporary_user, and third_party grant types. Optionally used by the refresh_token grant type. A space-separated list of scope(s) requested by the application.
  • token_type_hint string (values: access_token, refresh_token): 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.

Output

• output AccessTokenData

revokeToken

Our implementation follows the proposed IETF specification RFC-7009.

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.

npr_authorization.revokeToken({
  "Authorization": "",
  "token": ""
}, context)

Input

• input object
  • Authorization required string: 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.
  • token required string: The access token or refresh token that the client wants to have revoked.
  • token_type_hint string (values: access_token, refresh_token): A hint about the type of the token submitted for revocation. If unspecified, the default value is assumed to be access_token.

Output

• output object: An empty JSON object

Definitions

AbstractCDocLink

• AbstractCDocLink
  • href required string: The link to be followed
  • content-type required string: The MIME type of the response of this link

AbstractLink

• AbstractLink object
  • href required string: The link to be followed

AccessTokenData

• AccessTokenData object
  • access_token required string: The access token to use for all future calls
  • expires_in required integer: The remaining lifetime of the access token (in seconds)
  • refresh_token string: 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.
  • token_type required string (values: Bearer, MAC): Identifies the type of token returned. At this time, this field always has the value Bearer.

Affiliation

• Affiliation object: A program (aggregation) that a given user has shown an affiliation with
  • daysSinceLastListen integer: The number of days since a user last listened to a story from this aggregation. Absent if user never listened to the aggregation.
  • following required boolean: 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.
  • href required string: A link to more details about the program from the NPR Story API
  • id required string: A unique identifier for the aggregation (program)
  • notif_following array: 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 string
  • notif_rated array: 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 string
  • rating number: The user's average rating for this affiliation on a scale of 0-1. Absent if user never listened to the aggregation.
  • title string: The title for the aggregation (program)

CollectionDocument

• CollectionDocument object: Base Collection.Doc+JSON output
  • attributes required object
  • errors required array: A list of encountered errors, ignored on POST, PUT
    • items object
  • href required string: A URL representation of the resource; should generally be ignored by clients unless noted otherwise
  • items required array
    • items object
  • links required object
  • version required string: The version of the Collection.Doc+JSON spec being used

DeviceCodeData

• DeviceCodeData object
  • device_code required string: 40-character code for the device to input into the /token endpoint, not for display to the user
  • expires_in required integer: The number of seconds for which this set of codes will be valid, after which they will be purged
  • interval required integer: The number of seconds the client application should maintain between requests to the /token endpoint
  • user_code required string: 6-character alphanumeric code for the user to enter at http://npr.org/device, to be displayed by the client application
  • verification_uri required string: The URL where the user should input their code, to be displayed by the client application

Error

• Error object: A serialized version of any error encountered when processing this request
  • code required integer: The error code
  • debug string: Additional debug information if debug mode is turned on
  • text string: The error description

ErrorDocument

• ErrorDocument: A Collection.doc+JSON representation of an error result from an API call
  • attributes required object
  • errors required array: A list of encountered errors, ignored on POST, PUT
    • items object
  • href required string: A URL representation of the resource; should generally be ignored by clients unless noted otherwise
  • items required array
    • items object
  • links required object
  • version required string: The version of the Collection.Doc+JSON spec being used
  • attributes object: Ignore; will be empty for errors
  • errors array: A list of encountered errors, ignored on POST, PUT
    • items Error
  • items array: Ignore; will be empty for errors
    • items object
  • links object: Ignore; will be empty for errors

SimpleError

• SimpleError object: 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
  • message required string: A message describing the error that occurred
  • type required string: A short string representing the type of error that occurred