As a developer working with App.net, you are required to follow some simple rules to ensure that the privacy and security of user data is protected. To help you achieve that, we’ve put together this document on how to authenticate with App.net.
All requests to the API—authenticated or not—must be made over HTTPS. We use the OAuth 2.0 protocol for API authentication, but only certain portions of the specification. For instance, we only support the use of bearer tokens as access tokens. The specification is a little dense on the standards-speak, but we encourage you to take a look. We’ll explain our specific use of OAuth 2 in this document.
Once you have created an application, you will be assigned a client ID and client secret. You will use these in the authentication flow. The client ID may be publicly shared (e.g., included in a compiled binary or in the source code of a web page), but the client secret must be kept confidential.
You will also need to register a Redirect URI with App.net. This is where we will redirect users after they have successfully authorized your application.
It should go without saying, but for the sake of user privacy and security, please ensure that your App.net account has a strong password.
You authenticate to our API by use of an access token. There are two types of access tokens: app tokens and user tokens. App tokens (referred to as “client tokens” in the OAuth 2.0 standard) represent access to API resources on behalf of the application and user tokens represent access to API resources on behalf of a specific user. Some resources are only accessible to app or user tokens.
Only Apps created by a developer account can request access tokens for other App.net users. If you do not have a developer account, then your app can only be used with your own account. If you ever downgrade your developer account, all current tokens for your app will still work but no new users will be able to authorize it.
Each endpoint specifies the kind of token it needs:
Scopes let you specify what data your App wants from a User. They do not apply to app tokens. Scopes are specified on the initial access token request. A user will be able to see a list of the scopes you are requesting with explanations of what each of the scopes means. Your app should not assume that an access token has all the requested scopes.
When using an OAuth token, App.net will include an extra HTTP headers so the app knows what scopes that token has authorized. For example:
means that the current token has permission to follow new users and to create posts for this user.
Here is the current list of scopes on App.net:
The basic scope will always be granted on creation of a user access token, even if the token request omits it.
The messages, public_messages, and files scopes control access to a wide range of a user’s App.net data. Most apps will not need access to every type of Channel or File that a user has on App.net. For instance, a private message app probably doesn’t need access to your Broadcast channels. We provide extended scopes so an app can request access to just the channel (or file types) it needs instead of asking for the entire messages scope.
The general form of an extended scope is
basic_scope:content_type. So if your app only needs to access private messages, you can request the
messages:net.app.core.pm scope. If your app needs access to private messages and patter rooms, you can request
Please review the Content Types documentation for more information about how channel and file types work with extended scopes.
You can use extended scopes with the messages, public_messages, and files basic scopes. We encourage you to think about exactly what access your app needs to a user’s App.net account and use extended scopes instead of their more permissive basic scopes.
If you have an existing app and would like to migrate extended scopes, please see the extended scopes migration guide.
All of the OAuth endpoints for the App.net are rooted under
https://account.app.net/. Previously they were hosted under
https://alpha.app.net. The previous URLs will continue to function indefinitely.
If you're submitting your application to one of Apple's App Stores, you should not use any of the web based flows. We suggest you implement authentication via the Native App SDK flow with the Password Flow as a backup. Otherwise, it's possible your app will be rejected.
All OAuth errors will have the following information provided:
error— a single error code from one of the following lists (depending on which flow you’re going through)
error_description— a human readable error description.
If you’re requesting an
authorization_code from a user in the server-side web flow we’ll notify you of the error by appending it to your
redirect_uri as query string parameters.
If you’re requesting a token via the client-side web flow, we’ll append the error to your
redirect_uri as a URL encoded fragment.
For all other cases, the error will be returned as JSON in the response to your request.
Please ensure your application displays an error message to the user if you receive an error from App.net.
Please make sure that the
redirect_uri you’re passing to App.net is registered for your app in the Apps dashboard.
This app is owned by an account that isn’t a developer account. Remember, apps not owned by a developer account can only authorized the owner of the app. If you believe you have a developer account, please check to make sure your credit card is correct and that your account hasn’t been downgraded.
This often indicates a problem with the encoding of the request you’re sending us. Please make sure that you haven’t URL encoded the request body multiple times. Also please make sure you’re sending your request with a Content-type of
When making a call to one of our API resources, there are three ways to include authentication information.
In all of these examples,
<YOUR ACCESS TOKEN>is the user’s access token, free of any JSON framing or query string parameters.
Adding an Authorization header (preferred)
Add the following header to your request:
Authorization: Bearer <YOUR ACCESS TOKEN>
<YOUR ACCESS TOKEN> is the value of the user’s access token.
Here’s an example:
curl -X POST -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "X-ADN-Pretty-JSON: 1" \ -H "Content-Type: application/x-www-form-urlencoded" -d "text=Test post" \ "https://api.app.net/posts"
access_token to query string
curl -H "X-ADN-Pretty-JSON: 1" "https://api.app.net/posts/1?access_token=<YOUR ACCESS TOKEN>"
access_token to HTTP body.
This method will only work with the
DELETEdo not accept an HTTP body.
curl -X POST -H "X-ADN-Pretty-JSON: 1" -H "Content-Type: application/x-www-form-urlencoded" \ -d "text=Test post" -d "access_token=<YOUR ACCESS TOKEN>" \ "https://api.app.net/posts"
We call this Identity Delegation. The detailed Identity Delegation specification has its own page.