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"
}