Scopes
OAuth scopes are used to limit an application’s access to user data
During authorization, the API provider will display all the requested scopes to the user. This way, users will know what permissions they are granting to an application.
A minimal scope
Isolate scopes for protecting sensitive information
Differentiate scopes for different kinds of resources
GitHub has different scopes for accessing different resources, like the repositories, managing organization, public keys, notifications, and gists. This means that an application requesting access to only a user’s repositories will not be granted access to that user’s gists.
X-OAuth-Scopes lists the scopes for which a token has been authorized.
X-Accepted-OAuth-Scopes lists the scopes that the action requires.
Token Expiry and Refresh Tokens
A refresh token is a special type of token used to obtain a new access token when the current access token expires. Applications need to provide the client ID, client secret, and refresh token to generate a new access token. Refresh tokens are a standard way of renewing expired access tokens.
Even if your access tokens do not expire, it can be a good idea to share refresh tokens.
Short-lived authorization codes
One-time-use refresh tokens
it is a good idea to allow applications to use refresh tokens for a small window of time so that they can retry if there was a network failure or another issue. The Fitbit API allows a refresh token to be reused for up to two minutes.
Ability to reset the client secret
OAuth scopes for sensitive information
HTTPS endpoints
Verify redirect URL
Disallow rendering the authorization screen in iframes
Use the X-Frame-Options header to deny rendering an authorization page in an iframe.
Keep users informed
Prohibit misleading application names
Do not allow apps to use names that might mislead users into thinking that an outside application was created by your company. One way to enforce this is by denying apps permission to use your company name in OAuth application names.
WebHooks Security
Verification Tokens
Request Signing and WebHook Signatures
Signatures are among the most common ways API providers choose to secure WebHooks. WebHook payloads are typically signed by computing a hash-based message authentication code (HMAC) of a shared secret plus the request body, and the signature is sent as part of a request header. Applications then verify the authenticity of the request by computing the same HMAC and comparing it to the value set in the header
PREVENTING REPLAY ATTACKS
A replay attack is a form of attack in which an attacker retransmits a WebHook with a valid signature. To mitigate such attacks, API providers like Stripe include a request timestamp in the message payload. If the timestamp is too old, applications can reject the request.
Thin Payloads and API Retrieval
A more secure option is to send limited information in the payload indicating to the application that something has changed. To retrieve the full event, the application would need to make a subsequent request to the web API. The key benefit of this approach is that even if applications do not verify the WebHook, they will receive the full event only after making regular authenticated requests to a web API.
Gmail’s API allows applications to subscribe to watch for changes in an inbox using WebHooks. When something changes, Gmail sends a WebHook request, including the email address and an ID for the change. Applications can call Gmail’s history.list web API to retrieve the full change details.
