Dropto Tokens API

openapi: 3.2.0
info:
  title: Drop2Run.Api | v1 Tokens API
  version: 1.0.0
  description: Long-lived credentials for publishing from a script, a CI job or an agent. A token is shown once when it is created and is recoverable nowhere afterwards, so what is listed here is a name and a prefix rather than a secret.
servers:
- description: Production
  url: https://dropto.run
tags:
- description: Long-lived credentials for publishing from a script, a CI job or an agent. A token is shown once when it is created and is recoverable nowhere afterwards, so what is listed here is a name and a prefix rather than a secret.
  name: Tokens
paths:
  /api/tokens:
    get:
      operationId: ListTokens
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTokensResponse'
          description: OK
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Forbidden
      security:
      - session: []
      summary: Lists the account's access tokens, including revoked ones
      tags:
      - Tokens
    post:
      operationId: CreateToken
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTokenRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTokenResponse'
          description: Created
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Bad Request
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Forbidden
      security:
      - session: []
      summary: Issues an access token and returns its plaintext, which is not recoverable later
      tags:
      - Tokens
  /api/tokens/{tokenId}:
    delete:
      operationId: RevokeToken
      parameters:
      - in: path
        name: tokenId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeTokenResponse'
          description: OK
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Not Found
      security:
      - session: []
      summary: 'Revokes an access token. Idempotent: revoking a revoked token succeeds'
      tags:
      - Tokens
components:
  schemas:
    TokenSummary:
      description: One token as its owner sees it. Never carries the plaintext, which was not kept.
      properties:
        createdAt:
          description: When it was issued.
          format: date-time
          type: string
        expiresAt:
          description: When it stops working on its own, or null.
          format: date-time
          type:
          - 'null'
          - string
        id:
          description: ULID of the token.
          type: string
        lastUsedAt:
          description: When a request last authenticated with it, or null if never.
          format: date-time
          type:
          - 'null'
          - string
        name:
          description: What its owner called it.
          type: string
        prefix:
          description: Its first characters, which is all there is to tell two rows apart by.
          type: string
        revokedAt:
          description: When it was revoked, or null while it stands.
          format: date-time
          type:
          - 'null'
          - string
        source:
          description: 'How it came to exist: `Manual` (this page), `CommandLine` (a sign-in on the person''s machine)

            or `RemoteMcp` (a hosted chat''s connector, where revoking it disconnects that connector).'
          example: RemoteMcp
          type: string
      required:
      - id
      - name
      - prefix
      - createdAt
      - lastUsedAt
      - expiresAt
      - revokedAt
      - source
      type: object
    CreateTokenRequest:
      description: Request body of `POST /api/tokens`.
      properties:
        expiresInDays:
          description: How long it should last, or null for a token that never expires on its own.
          format: int32
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
        name:
          description: What to call the token, so its owner can tell it from their others.
          maxLength: 64
          minLength: 1
          type: string
      required:
      - name
      - expiresInDays
      type: object
    ProblemDetails:
      properties:
        detail:
          type:
          - 'null'
          - string
        instance:
          type:
          - 'null'
          - string
        status:
          format: int32
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
        title:
          type:
          - 'null'
          - string
        type:
          type:
          - 'null'
          - string
      type: object
    CreateTokenResponse:
      description: Response of `POST /api/tokens`.
      properties:
        createdAt:
          description: When it was issued.
          format: date-time
          type: string
        expiresAt:
          description: When it stops working on its own, or null.
          format: date-time
          type:
          - 'null'
          - string
        id:
          description: ULID of the new token.
          type: string
        name:
          description: The name it was given.
          type: string
        prefix:
          description: Its first characters, which is what every later listing shows.
          type: string
        token:
          description: The plaintext. Returned exactly once and recoverable nowhere.
          type: string
      required:
      - id
      - name
      - prefix
      - token
      - createdAt
      - expiresAt
      type: object
    ListTokensResponse:
      description: Response of `GET /api/tokens`.
      properties:
        accountTokens:
          description: 'What colleagues hold on the same account, and only what an owner is entitled to know about them.

            Empty for a member, and empty for an owner whose colleagues have none.


            A separate list rather than the same rows with fields blanked out, because a row that is sometimes

            missing its prefix is a row whose type is a lie — and the screen showing it has to branch

            on something either way.'
          items:
            $ref: '#/components/schemas/AccountTokenSummary'
          type: array
        tokens:
          description: The caller's own tokens on this account, newest first, including revoked ones.
          items:
            $ref: '#/components/schemas/TokenSummary'
          type: array
      required:
      - tokens
      - accountTokens
      type: object
    RevokeTokenResponse:
      description: Response of `DELETE /api/tokens/{tokenId}`.
      properties:
        id:
          description: ULID of the token that no longer works.
          type: string
        revokedAt:
          description: When it stopped working, which is unchanged if it already had.
          format: date-time
          type: string
      required:
      - id
      - revokedAt
      type: object
    AccountTokenSummary:
      description: Somebody else's token, as an owner of the account may see it.
      properties:
        email:
          description: Whose it is.
          type: string
        id:
          description: ULID of the token, which is what an owner revokes it by. A handle, not a credential.
          type: string
        lastUsedAt:
          description: When a request last authenticated with it, or null if never.
          format: date-time
          type:
          - 'null'
          - string
        name:
          description: What they called it, which is what makes a list of them readable.
          type: string
        revoked:
          description: Whether it has been revoked, as a flag rather than a date.
          type: boolean
      required:
      - id
      - email
      - name
      - lastUsedAt
      - revoked
      type: object
  securitySchemes:
    accessToken:
      description: 'A personal access token, created at /account/tokens. Sent as `Authorization: Bearer d2r_...`. A rejected token answers 401 with `invalid_token`, which is deliberately distinct from the 403 a valid credential gets for something it may not do.'
      scheme: bearer
      type: http
    claimToken:
      description: Returned once when an anonymous site is created, and the only credential that site has until somebody signs in and claims it.
      in: header
      name: X-Claim-Token
      type: apiKey
    session:
      description: The browser session, set by signing in with Google. HttpOnly, so a script cannot read it and a client outside a browser cannot send it.
      in: cookie
      name: d2r_session
      type: apiKey