openapi: 3.1.0
info:
  title: OwnID API
  version: 1.0.0
  description: Server API for integrating with the OwnID
servers:
  - url: https://server.ownid.com/{appId}
    #variables:
      #appId:
        #default: a1231232
        #description: Your OwnID Application ID
paths:
  /accounts/agent/{agentId}:
    get:
      tags:
        - Agents
      summary: Get details about an agent
      description: Returns detailed information for a specific AI agent based on the provided agentId.
      operationId: getAgent
      parameters:
        - name: agentId
          in: path
          required: true
          description: Unique identifier for the AI agent
          schema:
            type: string
        - name: Authorization
          in: header
          required: true
          description: Bearer Token for admin authorization
          schema:
            type: string
      responses:
        '200':
          description: Successful retrieval of agent data
          content:
            application/json:
              schema:
                type: object
                properties:
                  agentId:
                    type: string
                    description: The unique identifier for the AI agent
                    example: agent_12345
                  agentType:
                    type: string
                    description: The type of agent
                    example: browser-using
                  status:
                    type: string
                    description: Current status of the AI agent
                    example: active
                  createdAt:
                    type: string
                    format: date-time
                    description: Date and time the agent was created
                    example: 2025-01-01T12:34:56Z
                  updatedAt:
                    type: string
                    format: date-time
                    description: Date and time the agent was last updated
                    example: 2025-02-02T09:00:00Z
                  metadata:
                    type: object
                    description: Additional metadata about the agent
                    example:
                      notes: "This is a high-privilege AI agent."
        '400':
          description: Bad request or invalid agentId
        '401':
          description: Unauthorized or missing credentials
        '404':
          description: Agent not found
    delete:
      tags:
        - Agents
      summary: Revoke an agent
      description: Disables or revokes access for the specified AI agent, preventing further authentication or activity.
      operationId: deleteAgent
      parameters:
        - name: agentId
          in: path
          required: true
          description: Unique identifier for the AI agent
          schema:
            type: string
        - name: Authorization
          in: header
          required: true
          description: Bearer Token for admin authorization
          schema:
            type: string
      responses:
        '200':
          description: Successful revocation of the agent
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Agent revoked successfully.
        '400':
          description: Bad request or invalid agentId
        '401':
          description: Unauthorized or missing credentials
        '404':
          description: Agent not found
    put:
      tags:
        - Agents
      summary: Update details for a specific AI agent
      description: Modifies an AI agent’s information, such as status or metadata.
      operationId: updateAgent
      parameters:
        - name: agentId
          in: path
          required: true
          description: Unique identifier for the AI agent
          schema:
            type: string
        - name: Authorization
          in: header
          required: true
          description: Bearer Token for admin authorization
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  description: The new status for the AI agent
                  example: suspended
                agentType:
                  type: string
                  description: (Optional) Update the agent type if necessary
                  example: custom-ai
                metadata:
                  type: object
                  description: Additional metadata or information about the agent
                  example:
                    notes: "Updated due to new security policy."
      responses:
        '200':
          description: Successful update of agent data
          content:
            application/json:
              schema:
                type: object
                properties:
                  agentId:
                    type: string
                    description: The unique identifier for the AI agent
                    example: agent_12345
                  agentType:
                    type: string
                    description: The type of agent
                    example: custom-ai
                  status:
                    type: string
                    description: Current status of the AI agent
                    example: suspended
                  metadata:
                    type: object
                    description: Updated metadata about the agent
                    example:
                      notes: "Updated due to new security policy."
                  updatedAt:
                    type: string
                    format: date-time
                    description: Date and time the agent was last updated
                    example: 2025-02-15T12:00:00Z
        '400':
          description: Bad request or invalid input
        '401':
          description: Unauthorized or missing credentials
        '404':
          description: Agent not found

  /schema:
    get:
      summary: Retrieve a schema
      description: Returns the JSON-schema associated with a specified schema identifier.
      operationId: getSchema
      tags:
        - Profile Schema
      security: []
        #public endpoint
      responses:
        '200':
          description: Successfully retrieved the schema.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JSONSchema' 
              examples: 
                BasicProfileSchema:
                  $ref: '#/components/examples/BasicProfileSchema'
        '404':
          description: Schema with the requested identifier does not exist.
    post:
      summary: Set a schema
      description: Sets a JSON-schema for a specified schema identifier.
      operationId: setSchema
      tags:
        - Profile Schema
      security: 
        - AdminAccessToken: 
          - schema:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JSONSchema' 
            examples: 
                BasicProfileSchema:
                  $ref: '#/components/examples/BasicProfileSchema'
      responses:
        '204':
          description: Successfully set the schema.
        '400':
          description: Invalid schema data provided.
          
  /accounts:
    post:
      summary: Create a new account
      description: Creates a new account.
      operationId: createAccount
      tags:
        - Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              BasicAccountProfile:
                summary: Basic Account
                value:
                  profile:
                    firstName: Sassi
                    lastName: Keshet
      responses:
        '201':
          description: Successfully created a new account.
        '400':
          description: Invalid request data.
    delete:
      summary: Delete an account
      description: Deletes the specified account.
      operationId: deleteAccount
      tags:
        - Account
      responses:
        '204':
          description: Successfully deleted the account.
        '404':
          description: Account does not exist.
  /accounts/profile:
    get:
      summary: Retrieve an account's profile
      description: Returns the account profile data.
      operationId: getProfile
      tags:
        - Profile
      responses:
        '200':
          description: Successfully retrieved account data.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              examples:
                BasicProfile:
                  $ref: '#/components/examples/BasicProfile'
        '404':
          description: Account does not exist.
    
    put:
      summary: Update an existing account profile
      description: Updates the account profile data.
      operationId: updateProfile
      tags:
        - Profile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              BasicProfile:
                $ref: '#/components/examples/BasicProfile'
      responses:
        '202':
          description: Successfully updated the account.
        '404':
          description: Account does not exist.

  /accounts/sessions:
    get:
      summary: Retrieve all sessions for the account
      description: Returns all session data.
      operationId: getSessions
      tags:
        - Session
      responses:
        '200':
          description: Successfully retrieved all session data.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Session'
        '404':
          description: No sessions found for the requested account.
    post:
      summary: Create a new session
      description: Creates a new session.
      operationId: createSession
      tags:
        - Session
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              allOf:
                - properties:
                    expiration:
                      type: integer
                      minimum: 0
                - $ref: '#/components/schemas/WithSessionPayload'
      responses:
        '201':
          description: Successfully created a new session.
          headers: 
            Set-Cookie:
              description: Setting the session (access token) as a cookie
              schema:
                type: string
                regex: '^ownid-at=(.*); Path=/; HttpOnly; Secure;$'
                examples:
                  - 'ownid-at={accessToken};  Path=/; HttpOnly; Secure;'
          content:
            application/json: 
              schema:
                $ref: '#/components/schemas/Session'
        '400':
          description: Invalid request data.
  /accounts/sessions/{sessionId}:
    get:
      summary: Retrieve session data
      description: Returns session data associated with the specified `sessionId`.
      operationId: getSession
      tags:
        - Session
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
          description: The session ID.
      responses:
        '200':
          description: Successfully retrieved session data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '404':
          description: Session with the requested session ID does not exist.
    put:
      summary: Update an existing session
      description: Updates the session data associated with the specified `sessionId`.
      operationId: updateSession
      tags:
        - Session
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
          description: The session ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithSessionPayload'
      responses:
        '200':
          description: Successfully updated the session.
          content:
            application/json: 
              schema:
                $ref: '#/components/schemas/Session'
        '404':
          description: Session with the requested session ID does not exist.
    delete:
      summary: Delete a session
      description: Deletes the session associated with the specified `sessionId`.
      operationId: deleteSession
      tags:
        - Session
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
          description: The session ID.
      responses:
        '204':
          description: Successfully deleted the session.
        '404':
          description: Session with the requested session ID does not exist.
  
components:
  examples: 
    BasicProfile:
      summary: A simple account profile
      value:
        firstName: Sassi
        lastName: Keshet
    BasicProfileSchema:
      summary: JSON Schema of a basic Profile
      value:
        type: object
        properties:
          firstName:
            type: string
          lastName:
            type: string
  schemas:
    JSONSchema:
      #$ref: 'https://json-schema.org/draft-07/schema#'
      type: object
      additionalProperties: true
    Session:
      type: object
      required:
        - created
      allOf:
        - properties:
            created:
              type: string
              format: date-time
            timeout:
              type: integer
            lastActive:
              type: string
              format: date-time
        - $ref: '#/components/schemas/WithSessionPayload'
      examples: 
        - created: 2000-10-31T01:30:00.000-05:00
          timeout: 10000
          lastActive: 2000-10-31T01:30:00.000-05:00
          payload:
            preferences:
              theme: dark
              resolution: wide
    WithSessionPayload:
      properties:
        payload:
          type: object
          additionalProperties: true
      examples: 
        - payload:
            preferences:
              theme: dark
              resolution: wide
  securitySchemes:
    UserAccessToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
    AdminAccessToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
security: 
  #- UserAccessToken: []
  - AdminAccessToken: []