Tent v0.3-WIP Documentation

Note well: There is no guarantee of API stability until Tent v1.0.

Please contribute by making Pull Requests and Issues on the GitHub repository.

Apps

Apps allow users to interact with data in Tent. OAuth 2.0 combined with the Hawk authentication scheme are used for authorization and authentication.

Discovery

Typically an entity will provide the app with their Entity URL when logging in. Discovery must be performed on the URL in order to get the meta post with the list of servers and endpoints necessary to talk to the Tent servers that represent the entity.

HEAD entity
HEAD / HTTP/1.1
HTTP/1.1 200 OK
Link: </posts/http%3A%2F%2Fbb216a47d970.alpha.attic.is/meta>; rel="https://tent.io/rels/meta-post"
GET post
GET /posts/http%3A%2F%2Fbb216a47d970.alpha.attic.is/meta HTTP/1.1
Accept: application/vnd.tent.post.v0+json
HTTP/1.1 200 OK
Cache-Control: public, must-revalidate
Content-Type: application/vnd.tent.post.v0+json; type="https://tent.io/types/meta/v0#"
ETag: "SjG_Ap4yN5cF2iQhTU_8C239iEfxbTZzlJaB8xck7vQ"
Vary: Accept
{
  "post": {
    "content": {
      "entity": "http://bb216a47d970.alpha.attic.is",
      "profile": {},
      "servers": [
        {
          "version": "0.3",
          "preference": 0,
          "urls": {
            "oauth_auth": "http://bb216a47d970.alpha.attic.is/oauth",
            "oauth_token": "http://bb216a47d970.alpha.attic.is/oauth/authorization",
            "posts_feed": "http://bb216a47d970.alpha.attic.is/posts",
            "post": "http://bb216a47d970.alpha.attic.is/posts/{entity}/{post}",
            "new_post": "http://bb216a47d970.alpha.attic.is/posts",
            "post_attachment": "http://bb216a47d970.alpha.attic.is/posts/{entity}/{post}/attachments/{name}",
            "attachment": "http://bb216a47d970.alpha.attic.is/attachments/{entity}/{digest}",
            "batch": "http://bb216a47d970.alpha.attic.is/batch",
            "server_info": "http://bb216a47d970.alpha.attic.is/server"
          }
        }
      ]
    },
    "entity": "http://bb216a47d970.alpha.attic.is",
    "id": "meta",
    "published_at": 1372435655027,
    "type": "https://tent.io/types/meta/v0#",
    "version": {
      "id": "2857234617380a0a4f1f09ab15a3b7988624e5e054063090576f9c66f35b605b",
      "published_at": 1372435655027
    }
  }
}

Registration

Before going through the OAuth Authorization Grant flow for the first time, the app must be registered. Registration is the process of creating an app post using the new_post endpoint. The app post contains all of the metadata that the server needs from the app.

POST new_post
POST /posts HTTP/1.1
Content-Type: application/vnd.tent.post.v0+json; type="https://tent.io/types/app/v0#"
{
  "type": "https://tent.io/types/app/v0#",
  "content": {
    "name": "Example App",
    "url": "https://app.example.com",
    "types": {
      "read": [
        "https://tent.io/types/app/v0"
      ],
      "write": [
        "https://tent.io/types/status/v0",
        "https://tent.io/types/photo/v0"
      ]
    },
    "redirect_uri": "https://app.example.com/oauth"
  },
  "permissions": {
    "public": false
  }
}
HTTP/1.1 200 OK
Cache-Control: private, must-revalidate
Content-Type: application/vnd.tent.post.v0+json; type="https://tent.io/types/app/v0#"
Link: <http://bb216a47d970.alpha.attic.is/posts/http%3A%2F%2Fbb216a47d970.alpha.attic.is/G8txregRxB98_jnpq030fA?bewit=SnVPQi1CekI2MFpRazh2WVpNbDJvQVwxMzcyNDM2MzEyXFZlN0lMNDZEZERvR1JKVERCaXJBWjBpdmlwa3RiaDZNWVNSL2Z6YWNoR3c9XA>; rel="https://tent.io/rels/credentials"
{
  "post": {
    "content": {
      "name": "Example App",
      "url": "https://app.example.com",
      "types": {
        "read": [
          "https://tent.io/types/app/v0"
        ],
        "write": [
          "https://tent.io/types/status/v0",
          "https://tent.io/types/photo/v0"
        ]
      },
      "redirect_uri": "https://app.example.com/oauth"
    },
    "entity": "http://bb216a47d970.alpha.attic.is",
    "id": "KAS0j1n7pSsik8uub0QM7A",
    "mentions": [
      {
        "post": "G8txregRxB98_jnpq030fA",
        "public": false,
        "type": "https://tent.io/types/credentials/v0#"
      }
    ],
    "permissions": {
      "public": false
    },
    "published_at": 1372435712628,
    "received_at": 1372435712628,
    "type": "https://tent.io/types/app/v0#",
    "version": {
      "id": "df1cc3c968909723f7df2522c36cced866196ea2c238afa2f58a3cd5ea0ff26d",
      "published_at": 1372435712628,
      "received_at": 1372435712628
    }
  }
}

The response to the post creation request will include a Link header that contains a link to the credentials for the app. The credentials are used in the Access Token Request.

GET post
GET /posts/http%3A%2F%2Fbb216a47d970.alpha.attic.is/G8txregRxB98_jnpq030fA?bewit=SnVPQi1CekI2MFpRazh2WVpNbDJvQVwxMzcyNDM2MzEyXFZlN0lMNDZEZERvR1JKVERCaXJBWjBpdmlwa3RiaDZNWVNSL2Z6YWNoR3c9XA HTTP/1.1
Accept: application/vnd.tent.post.v0+json
HTTP/1.1 200 OK
Cache-Control: private, must-revalidate
Content-Type: application/vnd.tent.post.v0+json; type="https://tent.io/types/credentials/v0#https://tent.io/types/app/v0"
ETag: "cK-r0BOwcZ-kaFWCiqDozPe21Na5xu8uRZCE-UE7jxc"
Vary: Accept
{
  "post": {
    "content": {
      "hawk_key": "WResW4NIMzQZdLacnfy_gA",
      "hawk_algorithm": "sha256"
    },
    "entity": "http://bb216a47d970.alpha.attic.is",
    "id": "G8txregRxB98_jnpq030fA",
    "mentions": [
      {
        "post": "KAS0j1n7pSsik8uub0QM7A",
        "type": "https://tent.io/types/app/v0#"
      }
    ],
    "permissions": {
      "public": false
    },
    "published_at": 1372435712630,
    "received_at": 1372435712630,
    "type": "https://tent.io/types/credentials/v0#https://tent.io/types/app/v0",
    "version": {
      "id": "f6c99c80bb2636e25a275c7ff723e948c9dc1edf8a09c63020ca90dd69311979",
      "published_at": 1372435712630,
      "received_at": 1372435712630
    }
  }
}

OAuth

The oauth_auth and oauth_token endpoints are utilized for the OAuth Authorization Request and the Access Token Request respectively. Tent implements a subset of OAuth 2.0 that only supports the Authorization Code grant type. The authorization code is exchanged for the authorization’s Hawk credentials.

To authorize the app, redirect the user to the oauth_auth endpoint with the client_id URL parameter set to the id field from the previously created app post. If the app is web-based, the state parameter should also be set to a random value to be verified when the user is redirected back.

GET oauth_auth
GET /oauth?client_id=KAS0j1n7pSsik8uub0QM7A&state=d173d2bb868a HTTP/1.1
HTTP/1.1 302 Found
Location: https://app.example.com/oauth?code=m2lQJ-d87ueMyRmdYtcQXw&state=d173d2bb868a

After the user authorizes the application, the server will redirect to the app’s redirect_uri provided in the initial registration. The redirect URL will include a code parameter and the state parameter if provided in the initial redirect. The code is then traded by the application for authorized credentials that may be used to interact with the server. The access_token is used as the ID in Hawk signatures.

POST oauth_token
POST /oauth/authorization HTTP/1.1
Accept: application/json
Authorization: Hawk id="G8txregRxB98_jnpq030fA", mac="6YX1m3sheOW2yJSDPiI4i1riKNBRu5QOOucZ6q/AQQg=", ts="1372435713", nonce="dwXCGMQ1", hash="YbYsqRXw2fampy1rRk6py+HYjrFH7KzUITZslXwiyXU=", app="KAS0j1n7pSsik8uub0QM7A"
Content-Type: application/json
{
  "code": "m2lQJ-d87ueMyRmdYtcQXw",
  "token_type": "https://tent.io/oauth/hawk-token"
}
HTTP/1.1 200 OK
Cache-Control: private, must-revalidate
Content-Type: application/json; charset=utf-8
Server-Authorization: Hawk mac="GCBbe56vvxaDAiub18i7DILf3Q5P9d8JrNuctZpsfmE=", hash="bSj9G5h2gOzbO1CFaLu8QRLwm8L6GEuWj3/cdN1IQvA="
{
  "access_token": "7jDXOUbw4mePeVRGkI6nkA",
  "hawk_key": "m2lQJ-d87ueMyRmdYtcQXw",
  "hawk_algorithm": "sha256",
  "token_type": "https://tent.io/oauth/hawk-token"
}

App Registration Schema

Property Required Type Description
name Required String The name of the app.
description Optional String The description of the app.
url Required String The URL for the website of the app.
redirect_uri Required String The URL that will be used as OAuth redirect_uri.
notification_url Optional String The URL where post notifications will be delivered.
notification_types Optional Array of Strings The list of type URIs that the app wants to receive notifications about.
types Optional Object The list of type URIs that the app wants access to.
types.read Optional Array of Strings The list of type URIs that the app wants to read.
types.write Optional Array of Strings The list of type URIs that the app wants to read and modify.
scopes Optional Array of Strings The list of requested scopes.

Notifications