openapi: 3.1.0
info:
  title: Aghanim Server-to-Server Achievements Players' Subscriptions API
  description: "The Aghanim Server-to-Server API is designed for **backend server integrations only**. Use this API when you need to automate game hub updates from your server-side applications.\n\n\n## OpenAPI Specification\n\nYou can download the [OpenAPI](https://www.openapis.org/) specification for this API at the following link:\n[docs.aghanim.com/openapi.json](https://docs.aghanim.com/openapi.json).\n\n## Changelog\n\nSee the [S2S API Changelog](https://docs.aghanim.com/s2s-api/changelog/) for a history of changes to this API.\n\n## Authentication\n\nAghanim supports two methods of authentication: **Bearer token** and **Basic authentication**.\n\nTo authenticate, you will need your API key, which can be retrieved from\nthe Aghanim Dashboard → [**Game → Integration → API Keys**](https://dashboard.aghanim.com/go/integration/api-keys).\n\n**⚠️ Security Notice**: The S2S API key is **secret** and must be kept secure on your server. Never expose the S2S API key in client-side code, mobile apps, or any public-facing applications.\n\n### Bearer Token Authentication\n\nUse the Bearer method by including an `Authorization` header with the word `Bearer`\nfollowed by your API key. The `Authorization` header in your HTTP request should look like this: `Authorization: Bearer API_KEY`\n\n### Basic Authentication\n\nAlternatively, you can authenticate using Basic authentication. Your API key is used\nas the `username`, and the `password` should be left empty. Send an `Authorization`\nheader with the word `Basic` followed by a base64-encoded string\nin the format `API_KEY:` (note the colon at the end).\n\nThe `Authorization` header should look like this: `Authorization: Basic ZGVtbzpwQDU1dzByZA==`\n\n## Error Codes\n\nAghanim employs standard HTTP response codes to denote the success or failure of an API request.\nBelow is a table detailing error codes.\n\n| Code | Description |\n| ---- | ----------- |\n| 200  | OK          |\n| 400  | Bad request |\n| 401  | Not authenticated |\n| 403  | Not authorized |\n| 404  | Resource not found |\n| 409  | Conflict. Request conflicts with current state of resource |\n| 422  | Validation error |\n| 429  | Too many requests. Rate limit exceeded |\n| 503  | Server unavailable |\n\n### Generic error schema\n\n```json\n{\n  \"detail\": \"string\"\n}\n```\n\n### Validation error schema\n\n```json\n{\n  \"detail\": [\n    {\n      \"loc\": [\n        \"string\",\n        0\n      ],\n      \"msg\": \"string\",\n      \"type\": \"string\"\n    }\n  ]\n}\n```\n\n## Rate Limits\n\nThe Aghanim API has rate limiting in place to avoid overloading and to ensure it remains stable.\nThe allowable rate of requests is capped at 1,000 per minute for every game.\nGame developers who exceed this limit will receive a 429 error code.\n\nTo increase the rate limit, please contact us via [integration@aghanim.com](mailto:integration@aghanim.com).\n\n## Pagination\n\nIn the Aghanim API, pagination is managed through the use of the `limit` and `offset` query parameters.\nThese parameters allow to fine-tune your data retrieval requests by specifying:\n\n- `limit`: the number of records to be returned in a single request.\n- `offset`: indicates the number of records to skip from the start of the dataset.\n"
  contact:
    name: Aghanim
    email: integration@aghanim.com
  version: 2026.07.14
servers:
- url: https://api.aghanim.com/s2s
  description: Production
tags:
- name: Players' Subscriptions
paths:
  /v1/players/{player_id}/subscriptions:
    get:
      tags:
      - Players' Subscriptions
      summary: Get Subscriptions
      description: Retrieve subscriptions for a player.
      operationId: get_player_subscriptions
      security:
      - HTTPBearer: []
      parameters:
      - name: player_id
        in: path
        required: true
        schema:
          title: Player Id
          type: string
      - name: effective
        in: query
        required: false
        schema:
          title: Effective
          description: Filter by effective status. True for effective only, False for non-effective only, None for all.
          type: boolean
        description: Filter by effective status. True for effective only, False for non-effective only, None for all.
      - name: limit
        in: query
        required: false
        schema:
          title: Limit
          description: A limit on the number of objects to be returned
          default: 10
          type: integer
        description: A limit on the number of objects to be returned
      - name: offset
        in: query
        required: false
        schema:
          title: Offset
          description: The number of objects to skip
          type: integer
        description: The number of objects to skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Get Player Subscriptions
                type: array
                items:
                  $ref: '#/components/schemas/aghanim__s2s__player__subscription__schemas__SubscriptionRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/players/{player_id}/subscriptions/{subscription_id}:
    delete:
      tags:
      - Players' Subscriptions
      summary: Cancel Player Subscriptions
      description: Cancel a players's subscription.
      operationId: cancel_player_subscriptions
      security:
      - HTTPBearer: []
      parameters:
      - name: player_id
        in: path
        required: true
        schema:
          title: Player Id
          type: string
      - name: subscription_id
        in: path
        required: true
        schema:
          title: Subscription Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/players/{player_id}/subscriptions/{subscription_id}/reactivate:
    post:
      tags:
      - Players' Subscriptions
      summary: Reactivate Player Subscription
      description: "Reactivate a player's subscription.\n\nDepending on the current subscription state:\n  - reactivates the existing subscription if it is not in a terminal state,\n  - creates a new subscription if the previous one has ended,\n  - or does nothing if the subscription is already active."
      operationId: reactivate_player_subscription
      security:
      - HTTPBearer: []
      parameters:
      - name: player_id
        in: path
        required: true
        schema:
          title: Player Id
          type: string
      - name: subscription_id
        in: path
        required: true
        schema:
          title: Subscription Id
          type: string
      responses:
        '200':
          description: Subscription reactivated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReactivatedSubscription'
        '201':
          description: New subscription created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReactivatedSubscription'
        '204':
          description: Subscription already active.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    aghanim__s2s__player__subscription__schemas__SubscriptionRead:
      properties:
        sku:
          type: string
          title: SKU
          description: Subscription unique SKU.
        id:
          type: string
          title: Id
          description: Unique identifier for this subscription instance. Use this ID to track and manage the subscription throughout its lifecycle.
        name:
          type: string
          title: Name
          description: Subscription display name.
        order_id:
          type: string
          title: Order Id
          description: Order ID where the subscription was originally activated. Use this to correlate with order webhooks.
        status:
          description: Subscription status.
          $ref: '#/components/schemas/SubscriptionStatus'
        created_at:
          type: integer
          title: Created At
          description: Subscription creation date in Unix epoch time (seconds).
        updated_at:
          type: integer
          title: Updated At
          description: Subscription last update date in Unix epoch time (seconds). Null if the subscription has not been updated.
        effective_until:
          type: integer
          title: Effective Until
          description: The date until which the subscription is effective in Unix epoch time (seconds) representing when the subscription benefits should remain accessible.
        metadata:
          type: object
          title: Metadata
          description: Custom key-value pairs attached to the subscription. Null if no metadata is set.
        plan:
          title: Plan
          description: Selected plan for the subscription.
          $ref: '#/components/schemas/Plan'
      type: object
      required:
      - sku
      - id
      - name
      - order_id
      - status
      - created_at
      - plan
      title: SubscriptionRead
    ReactivatedSubscription:
      properties:
        id:
          type: string
          title: Id
          description: Resulting subscription ID.
        status:
          description: Resulting subscription status.
          $ref: '#/components/schemas/SubscriptionStatus'
      type: object
      required:
      - id
      - status
      title: ReactivatedSubscription
    Offer:
      properties:
        key:
          type: string
          title: Key
          description: Offer unique key.
        name:
          type: string
          title: Name
          description: Offer display name.
      type: object
      required:
      - key
      title: Offer
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SubscriptionStatus:
      type: string
      enum:
      - trial
      - active
      - grace
      - canceled
      - locked
      - ended
      - expired
      - paused
      - pending
      title: SubscriptionStatus
      description: An enumeration.
    Plan:
      properties:
        key:
          type: string
          title: Key
          description: Plan unique key within subscription.
        name:
          type: string
          title: Name
          description: Plan display name.
        offer:
          title: Offer
          description: Offer applied to the plan. Null if no offer is applied.
          $ref: '#/components/schemas/Offer'
      type: object
      required:
      - key
      - name
      title: Plan
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
      description: Refer to the [Authentication](https://docs.aghanim.com/api-reference/) section for instructions on obtaining an API key and use it as the `Bearer` token.