asoskill-com Authentication API

openapi: 3.2.0
info:
  title: ASO Skill Developer Authentication API
  version: 1.0.0
  description: 'Customer-facing API for App Store keyword search, autocomplete, difficulty,

    popularity, app metadata, credit balances, and credit purchases. Every successful data

    response costs one credit. Rejected requests and failed upstream calls do

    not consume a credit.


    Major versions are encoded in the URL. Existing `/v1/` operations do not

    receive intentional breaking changes; compatible additions may ship within

    v1, while breaking replacements use a new path such as `/v2/`. When

    practical, deprecated operations remain available for at least six months

    and return the RFC 9745 `Deprecation` header, a migration `Link` with

    `rel="deprecation"`, and an RFC 8594 `Sunset` header once removal is

    scheduled. See the developer guide for the complete policy.'
  contact:
    name: ASO Skill support
    email: viktor@asosuite.com
  license:
    name: Proprietary; use governed by the ASO Skill Terms
    url: https://www.asoskill.com/terms
servers:
- url: https://api.asoskill.com
  description: Production
security:
- bearerApiKey: []
tags:
- name: Authentication
  description: Browser-assisted agent login and credential lifecycle
paths:
  /v1/auth/device:
    post:
      tags:
      - Authentication
      security: []
      operationId: startDeviceAuthorization
      summary: Start browser-assisted agent login
      description: Creates a short-lived connection request. The agent opens the returned verification URL, the account owner signs in and approves the requested permissions, and the agent polls the token endpoint. This request does not cost a credit.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceAuthorizationRequest'
      responses:
        '201':
          description: Short-lived browser authorization request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceAuthorizationResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/auth/device/token:
    post:
      tags:
      - Authentication
      security: []
      operationId: exchangeDeviceAuthorization
      summary: Poll and exchange an approved agent login
      description: Returns authorization_pending until the account owner acts. After approval, returns a retry-safe encrypted API-key envelope that only the initiating client can decrypt. This request does not cost a credit.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceTokenRequest'
      responses:
        '200':
          description: Encrypted API credential and metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceTokenResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AuthorizationDenied'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/auth/credential:
    delete:
      tags:
      - Authentication
      operationId: revokeCurrentCredential
      summary: Revoke the calling API key
      description: Revokes the bearer API key used for this request. Revocation can take up to five minutes to propagate through the authorizer cache. This request does not cost a credit.
      responses:
        '200':
          description: Credential revoked or already revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeCredentialResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountUnavailable'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    ApiError:
      type: object
      description: Machine-readable error details. Clients should branch on code and present message when useful; additional fields provide error-specific recovery context.
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Stable snake_case identifier suitable for programmatic handling
          example: invalid_request
        message:
          type: string
          description: Human-readable explanation that is safe to show to the account owner
          example: The request body is invalid
        retryAfterSeconds:
          type: integer
          minimum: 1
          description: Suggested delay for a retryable failure, when applicable
      additionalProperties: true
    RevokeCredentialResponse:
      type: object
      required:
      - id
      - status
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          const: revoked
        revokedAt:
          type: string
          format: date-time
    GatewayMessage:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          example: Too Many Requests
    ApiKeyScope:
      type: string
      enum:
      - data
      - credits
      - checkout
    DeviceTokenResponse:
      type: object
      required:
      - tokenType
      - credential
      - apiKey
      properties:
        tokenType:
          type: string
          const: Bearer
        credential:
          $ref: '#/components/schemas/CredentialEnvelope'
        apiKey:
          type: object
          required:
          - id
          - name
          - scopes
          - expiresAt
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
            scopes:
              type: array
              items:
                $ref: '#/components/schemas/ApiKeyScope'
            expiresAt:
              type:
              - string
              - 'null'
              format: date-time
    DeviceAuthorizationResponse:
      type: object
      required:
      - deviceCode
      - userCode
      - verificationUri
      - verificationUriComplete
      - expiresIn
      - interval
      properties:
        deviceCode:
          type: string
          description: High-entropy secret retained only by the initiating client
        userCode:
          type: string
          pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZ]{4}-[23456789ABCDEFGHJKLMNPQRSTUVWXYZ]{4}$
        verificationUri:
          type: string
          format: uri
        verificationUriComplete:
          type: string
          format: uri
        expiresIn:
          type: integer
          minimum: 1
        interval:
          type: integer
          minimum: 1
    ErrorResponse:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/ApiError'
    CredentialEnvelope:
      type: object
      required:
      - algorithm
      - iv
      - ciphertext
      - tag
      additionalProperties: false
      properties:
        algorithm:
          type: string
          const: A256GCM
        iv:
          type: string
        ciphertext:
          type: string
        tag:
          type: string
    DeviceTokenRequest:
      type: object
      required:
      - deviceCode
      - codeVerifier
      additionalProperties: false
      properties:
        deviceCode:
          type: string
          minLength: 32
          maxLength: 256
        codeVerifier:
          type: string
          pattern: ^[A-Za-z0-9_-]{43,128}$
    DeviceAuthorizationRequest:
      type: object
      required:
      - codeChallenge
      - name
      - scopes
      additionalProperties: false
      properties:
        codeChallenge:
          type: string
          pattern: ^[A-Za-z0-9_-]{43}$
        name:
          type: string
          minLength: 1
          maxLength: 80
        scopes:
          type: array
          minItems: 1
          maxItems: 3
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ApiKeyScope'
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
  responses:
    NotFound:
      description: The requested resource was not found; no credit is consumed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    AuthorizationDenied:
      description: The account owner denied the connection request; no credit is consumed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Request capacity or a rate allowance was exceeded; no credit is consumed. Respect Retry-After when present, otherwise retry with exponential backoff and jitter.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - $ref: '#/components/schemas/GatewayMessage'
    AccountUnavailable:
      description: The account is unavailable or disabled; no credit is consumed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Unexpected processing failure; any reserved credit is restored
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InvalidRequest:
      description: The request body or parameters are invalid; no credit is consumed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: The bearer credential is missing, invalid, expired, or revoked; no credit is consumed
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - $ref: '#/components/schemas/GatewayMessage'
  headers:
    RetryAfter:
      description: Number of seconds to wait before retrying. When absent, use exponential backoff with jitter.
      schema:
        type: integer
        minimum: 1
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: aso_live_...
      description: 'Long-lived secret created in the ASO Skill developer dashboard. Send it as `Authorization: Bearer <key>` and keep it on the server.'
    mcpOAuth:
      type: oauth2
      description: OAuth authorization code with S256 PKCE, dynamic client registration, exact MCP resource binding, refresh rotation, and revocation.
      flows:
        authorizationCode:
          authorizationUrl: https://api.asoskill.com/oauth/authorize
          tokenUrl: https://api.asoskill.com/oauth/token
          refreshUrl: https://api.asoskill.com/oauth/token
          scopes:
            data: Search, autocomplete, popularity, and app metadata tools
            credits: Read the connected account credit balance
externalDocs:
  description: Developer guide, including versioning and deprecation policy
  url: https://www.asoskill.com/developers#versioning
x-api-versioning:
  strategy: path
  currentMajorVersion: v1
  backwardCompatibleChangesWithinMajor: true
  minimumDeprecationPeriod: P6M
  policy: https://www.asoskill.com/developers#versioning