What's this

Introduction

Read this section to learn about the Authentication endpoints and their features

As a developer working with 10Centuries, 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 10Centuries.
All requests to the API—authenticated or not—must be made over HTTPS. We use the X-Auth for API authentication and support for the OAuth 2.0 protocol is on its way. This document will explain how to use the existing X-Auth authentication methods.

Sections

  1. Getting an Access Token
  2. Authentication Procedure
  3. Logging Out
  4. Checking Token Status

Initial Developer Setup

Before you begin, make sure you've created an application in your 10Centuries dashboard.

Once you have created an application, you will be assigned a Client GUID. You will use this in the authentication flow. The Client GUID must not be publicly shared (e.g., included in the source code of a web page).

Please ensure that your 10Centuries account has a sufficiently strong password to prevent losers from logging in as you, stealing your client keys, and otherwise making a mess of things.

Access Tokens

Access tokens are used to authenticate requests against the 10Centuries API, and a Client GUID is used during the authentication process to create access tokens. Not all API endpoints require the use of an access token.

Token Types

Endpoints can return different degrees of information based on the access token passed.

  • None: No Access Token is Required
  • User: An Access Token is Required
  • Varies: Limited Data is Returned Without a Token, and Complete Data is Returned With a Token

Getting an Access Token

Access tokens are currently only granted through the 10Centuries API by passing a valid Client GUID along with an account's login and password. This is referred to as the Resource Owner Password Credential flow in the OAuth 2.0 specification. Logins are currently only in the form of email addresses, though this will change to include personal website URLs and social account names. Regardless of how many social accounts or websites a person may have, they will only need one access token to access them all.

Rules

Security of accounts is absolutely essential. Try with the might of Thor to protect people's information.

Authentication Procedure

In the near future, account-holders will receive an email each time they sign into an application for the first time. Accounts can prevent 3rd-party services from using their credentials in their settings. If a client is prevented from logging in, a standard "Unrecognized Credentials" error will be returned.

From your application, send a request to the following endpoint:

POST https://api.10centuries.org/auth/login

Valid Variables:

acctname={account name} acctpass={password} client_guid={your Client GUID}

This information can be send URL-encoded in the POST body or as a JSON package.

Example:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_guid={your Client GUID}" \ -d "acctname=[email protected]" \ -d "acctpass=correct horse battery staple" \ "https://api.10centuries.org/auth/login"

If the authorization was successful, the API will respond with a JSON package:

{ "meta": { "code": 200 }, "data": { "token": "{A Valid Authentication Token}" } }

You can use the token to make authenticated calls to the 10Centuries API on behalf of an account.

If authentication failed or there was some other problem, the API will respond with an error:

{ "meta": { "code": 404, "text": "Unrecognized Credentials" }, "data": false }

If the meta.text key is present in this result, you must show a modal dialog or equivalent containing this message.

Logging Out

When a person logs out of their account, the authorization token will be expired and no longer available for use. While this might not occur very often, it can be performed by sending a request to the following endpoint:

POST https://api.10centuries.org/auth/logout

No variables are required for this endpoint, but the authorization token must be included. This information should be sent in the HTTP header.

Example:

curl -X POST -H "Authorization: {Authorization Token}" \ "https://api.10centuries.org/auth/logout"

If the authorization was successful, the API will respond with a JSON package:

{ "meta": { "code": 200 }, "data": { "is_active": false, "updated_at": "2016-02-20T07:29:28Z", "updated_unix": 1455953368 } }

Sending an invalid authorization token will result in the following JSON package:

{ "meta": { "code": 403, "more": false }, "data": "Invalid Authentication Supplied" }

Checking Token Status

Once a token is granted, they remain valid until authorization is revoked either by the account-holder logging out of the application, or revoking access to your app from the 10Centuries dashboard. You can always check the validity of an authorization token by sending a request to the following endpoint:

GET https://api.10centuries.org/auth/status

No variables are required for this endpoint, but the authorization token must be included. This information should be sent in the HTTP header.

Example:

curl -X GET -H "Authorization: {Authorization Token}" \ "https://api.10centuries.org/auth/status"

If the authorization was successful, the API will respond with a JSON package:

{ "meta": { "code": 200 }, "data": { "account": {Account Object}, "is_active": true, "updated_at": "2016-02-20T07:29:28Z", "updated_unix": 1455953368 } }

If the authorization token has expired or is otherwise invalid, the API will respond with a JSON package:

{ "meta": { "code": 200 }, "data": { "account": false, "is_active": false, "updated_at": false, "updated_unix": false } }