Authorization

Using this part of the API you can create new authorizations with access tokens, needed to access the rest of the API. See also the Authentication section in the overview.

Objects

Authorization

The authorization object describes an authorization. It enables you to use the API to access specified resources using an associated access token.

Example

{
  "id": 123456,
  "user_id": "uscdb",
  "token": "7qkM4rLTFfbEZMCVrZoHk3bCw4uTCG",
  "note": "This is my testing token",
  "resources": [
    {
      "type": "feed",
      "name": "200242",
      "permissions": ["r"]
    }
  ],
  "last_used_at": null,
  "expires_at": "2017-03-01T12:30:00+00:00"
}

Properties

Name Type Description
id integer Authorization ID. It uniquely identifies the authorization within the system.
user_id string ID of the user who owns the authorization.
token string Access token. To be put into the Authorization HTTP header.
note string User note.
resources array List of resources associated with the authorization.
last_used_at string | null Time when the authorization was last used, in ISO 8601 format. The value null means the authorization wasn’t used yet.
expires_at string Time when the authorization expires, in ISO 8601 format.

Resource

The resource object describes a resource — a subject of authorization. There are 2 types of resources:

User
Allows access to /users/{user_id} and all its subresources.
Feed
Allows access to /feeds/{feed_id} and all its subresources.

Note

For technical reasons, the API may use additional undocumented resource types and may associate resources of these types with created authorizations. These resources should be ignored.

Example

{
  "type": "feed",
  "name": "200242",
  "permissions": ["r"]
}

Properties

Name Type Description
type string Resource type, one of "user" or "feed" (but see note).
name string Resource identification. For resources of type "user", it is the user ID. For resources of type "feed", it is the feed ID.
permissions array List of permissions associated with the resource, can contain values "c" (create), "r" (read), "u" (update), "d" (delete).

Resources

POST /authorizations

Creates a new authorization. Returns an authorization object.

The request must be authorized using HTTP Basic authentication with user’s username and password. It must contain an object with the following properties:

Name Type Description
note string User note for the created authorization. Optional, default: "".
resources array List of resources associated with the created authorization. Optional, default: all resources the user is authorized to access.
valid_minutes integer How long from now should the created authorization be valid, in minutes. Optional, default: 43200 (30 days).

Example request

{
   "note": "This is my testing token",
   "resources": [
      {
         "type": "feed",
         "name": "200242",
         "permissions": ["r"]
      }
   ],
   "valid_minutes": 1440
}

Example response

{
  "id": 123456,
  "user_id": "uscdb",
  "token": "7qkM4rLTFfbEZMCVrZoHk3bCw4uTCG",
  "note": "This is my testing token",
  "resources": [
    {
      "type": "feed",
      "name": "200242",
      "permissions": ["r"]
    }
  ],
  "last_used_at": null,
  "expires_at": "2017-03-01T12:30:00+00:00"
}