> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Access Request

> Create an access request for a role. The request will go through the configured approval flow before access is provisioned.



## OpenAPI

````yaml /sections/api-reference/openapi-spec-v2.yaml post /v2/access-requests
openapi: 3.1.0
info:
  title: Serval Public API
  description: Serval Public API
  contact:
    name: Serval
    url: https://serval.com
    email: support@serval.com
  license:
    name: Serval License
    url: https://serval.com/license
  version: 2.0.0
servers:
  - url: https://public.api.serval.com
security:
  - BearerAuth: []
tags:
  - name: Access Policy API
  - name: Access Policy Approval Procedure API
  - name: Access Profile API
  - name: Access Relationship API
  - name: Access Request API
  - name: Agent Session API
  - name: App Instance API
  - name: App Resource API
  - name: App Resource Role API
  - name: Approval Delegation API
  - name: Approval Request API
  - name: Audit Log API
  - name: Change Blackout API
  - name: Change Model API
  - name: Custom Field API
  - name: Custom Service API
  - name: Entity API
  - name: Entity Field Mapping API
  - name: Entity Ingestion Config API
  - name: Entity Type API
  - name: Group API
  - name: Guidance API
  - name: Help Agent API
  - name: Journey API
  - name: Knowledge API
  - name: Knowledge Base API
  - name: Report API
  - name: SLA API
  - name: Schedule API
  - name: Tag API
  - name: Team API
  - name: Team User API
  - name: Ticket API
  - name: Topic API
  - name: User API
  - name: User Relationship API
  - name: Workflow API
  - name: Workflow Approval Procedure API
  - name: Workflow Run API
paths:
  /v2/access-requests:
    post:
      tags:
        - Access Request API
      summary: Create Access Request
      description: >-
        Create an access request for a role. The request will go through the
        configured approval flow before access is provisioned.
      operationId: svrelay.publicv2.PublicAPIServiceV2.CreateAccessRequest
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/svflow.publicapi.CreateAccessRequestRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/svflow.publicapi.CreateAccessRequestResponse
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/connect.error'
      security:
        - BearerAuth: []
components:
  schemas:
    svflow.publicapi.CreateAccessRequestRequest:
      type: object
      properties:
        teamId:
          type: string
          title: team_id
          description: The ID of the team. Required.
          x-stainless-terraform-configurability: required
        roleId:
          type: string
          title: role_id
          description: The ID of the role (entitlement) to request access for. Required.
          x-stainless-terraform-configurability: required
        targetUserId:
          type: string
          title: target_user_id
          description: >-
            The ID of the user to request access for. Defaults to the
            authenticated user if omitted.
          nullable: true
          x-stainless-terraform-configurability: computed_optional
        accessMinutes:
          type: integer
          title: access_minutes
          format: int32
          description: >-
            The duration of access in minutes. Must not exceed the role's
            max_access_minutes.
             Required unless the role has no maximum duration.
          x-stainless-terraform-configurability: optional
        businessJustification:
          type: string
          title: business_justification
          description: |-
            A business justification for the access request.
             Required if the role's access policy requires justification.
          nullable: true
          x-stainless-terraform-configurability: optional
        scheduledStartAt:
          type: string
          title: scheduled_start_at
          description: |-
            An optional scheduled start time for provisioning (RFC3339 format).
             If omitted, access is provisioned immediately upon approval.
          nullable: true
          x-stainless-terraform-configurability: optional
      title: CreateAccessRequestRequest
      required:
        - teamId
        - roleId
      additionalProperties: false
    svflow.publicapi.CreateAccessRequestResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/svflow.pubapimodels.AccessRequest'
          title: data
          description: The created access request.
          x-stainless-terraform-configurability: optional
      title: CreateAccessRequestResponse
      additionalProperties: false
    connect.error:
      type: object
      properties:
        code:
          type: string
          examples:
            - not_found
          enum:
            - canceled
            - unknown
            - invalid_argument
            - deadline_exceeded
            - not_found
            - already_exists
            - permission_denied
            - resource_exhausted
            - failed_precondition
            - aborted
            - out_of_range
            - unimplemented
            - internal
            - unavailable
            - data_loss
            - unauthenticated
          description: >-
            The status code, which should be an enum value of
            [google.rpc.Code][google.rpc.Code].
          x-stainless-terraform-configurability: optional
        message:
          type: string
          description: >-
            A developer-facing error message, which should be in English. Any
            user-facing error message should be localized and sent in the
            [google.rpc.Status.details][google.rpc.Status.details] field, or
            localized by the client.
          x-stainless-terraform-configurability: optional
        detail:
          $ref: '#/components/schemas/google.protobuf.Any'
          x-stainless-terraform-configurability: optional
      title: Connect Error
      additionalProperties: true
      description: >-
        Error type returned by Connect:
        https://connectrpc.com/docs/go/errors/#http-representation
    svflow.pubapimodels.AccessRequest:
      type: object
      properties:
        id:
          type: string
          title: id
          description: The unique ID of the access request.
          x-stainless-terraform-configurability: optional
        teamId:
          type: string
          title: team_id
          description: The ID of the team that the access request belongs to.
          x-stainless-terraform-configurability: optional
        status:
          $ref: '#/components/schemas/svflow.common.models.AccessRequestStatus'
          title: status
          description: The status of the access request.
          x-stainless-terraform-configurability: optional
        createdAt:
          type: string
          title: created_at
          description: The timestamp when the access request was created.
          x-stainless-terraform-configurability: optional
        targetUserId:
          type: string
          title: target_user_id
          description: The ID of the target user for whom access was requested.
          x-stainless-terraform-configurability: optional
        requestedRoleId:
          type: string
          title: requested_role_id
          description: The ID of the requested role.
          x-stainless-terraform-configurability: optional
        expiresAt:
          type: string
          title: expires_at
          description: >-
            The timestamp when the currently active time allocation expires.
            This is
             only set when the access request has been provisioned and is not yet
             concluded. If the request has been extended, this reflects the expiry of
             the latest (current) time allocation, not the original one.
          nullable: true
          x-stainless-terraform-configurability: optional
        linkedTicketId:
          type: string
          title: linked_ticket_id
          description: >-
            The ID of the ticket that originated this access request. This
            always
             matches the linked_ticket_id of the first time allocation. Extensions
             may be created from a different ticket — see each time allocation's
             linked_ticket_id for that.
          nullable: true
          x-stainless-terraform-configurability: optional
        timeAllocations:
          type: array
          items:
            $ref: >-
              #/components/schemas/svflow.pubapimodels.AccessRequestTimeAllocation
          title: time_allocations
          description: |-
            Every access request contains one or more time allocations. A time
             allocation represents a discrete grant (or pending grant) of access for a
             specific duration. The first time allocation is created with the initial
             request. When a user extends an existing access request, a new time
             allocation is appended — the previous one is invalidated (superseded) and
             the new one becomes the active or pending allocation. At most one time
             allocation is active and at most one is pending at any given time.

             Ordered by creation time ascending.
          readOnly: true
          x-stainless-terraform-configurability: computed
      title: AccessRequest
      additionalProperties: false
      description: AccessRequest represents a request for access to an entitlement.
    google.protobuf.Any:
      type: object
      properties:
        type:
          type: string
          x-stainless-terraform-configurability: optional
        value:
          type: string
          format: binary
          x-stainless-terraform-configurability: optional
        debug:
          type: object
          additionalProperties: true
          x-stainless-terraform-configurability: optional
      additionalProperties: true
      description: >-
        Contains an arbitrary serialized message along with a @type that
        describes the type of the serialized message.
    svflow.common.models.AccessRequestStatus:
      type: string
      title: AccessRequestStatus
      enum:
        - ACCESS_REQUEST_STATUS_UNSPECIFIED
        - ACCESS_REQUEST_STATUS_PENDING
        - ACCESS_REQUEST_STATUS_APPROVED
        - ACCESS_REQUEST_STATUS_DENIED
        - ACCESS_REQUEST_STATUS_EXPIRED
        - ACCESS_REQUEST_STATUS_REVOKED
        - ACCESS_REQUEST_STATUS_CANCELED
        - ACCESS_REQUEST_STATUS_FAILED
      description: |-
        AccessRequestStatus represents the overall status of an access request.
         Used by the public API for SDK consumers.
    svflow.pubapimodels.AccessRequestTimeAllocation:
      type: object
      properties:
        id:
          type: string
          title: id
          description: The unique ID of the time allocation.
          readOnly: true
          x-stainless-terraform-configurability: computed
        status:
          $ref: >-
            #/components/schemas/svflow.pubapimodels.AccessRequestTimeAllocationStatus
          title: status
          description: The status of this time allocation.
          readOnly: true
          x-stainless-terraform-configurability: computed
        createdAt:
          type: string
          title: created_at
          description: The timestamp when the time allocation was created.
          readOnly: true
          x-stainless-terraform-configurability: computed
        requestedMinutes:
          type: integer
          title: requested_minutes
          format: int32
          description: The number of minutes of access requested in this time allocation.
          readOnly: true
          x-stainless-terraform-configurability: computed
        approvedMinutes:
          type: integer
          title: approved_minutes
          format: int32
          description: >-
            The number of minutes actually approved. Null while the time
            allocation is pending.
          nullable: true
          readOnly: true
          x-stainless-terraform-configurability: computed
        businessJustification:
          type: string
          title: business_justification
          description: The business justification provided for this time allocation.
          nullable: true
          readOnly: true
          x-stainless-terraform-configurability: computed
        requestedByUserId:
          type: string
          title: requested_by_user_id
          description: >-
            The ID of the user who requested this time allocation (may differ
            from
             the original requester for extensions).
          readOnly: true
          x-stainless-terraform-configurability: computed
        invalidationReason:
          $ref: >-
            #/components/schemas/svflow.pubapimodels.AccessRequestTimeAllocationInvalidationReason
          title: invalidation_reason
          description: >-
            Why the time allocation was invalidated. Only set when status is
            INVALIDATED.
          nullable: true
          readOnly: true
          x-stainless-terraform-configurability: computed
        linkedTicketId:
          type: string
          title: linked_ticket_id
          description: >-
            The ID of the ticket this time allocation was created from, if any.
            For
             the initial allocation this is the ticket that originated the access
             request. For extensions this may be a different ticket.
          nullable: true
          readOnly: true
          x-stainless-terraform-configurability: computed
        approvalRequestId:
          type: string
          title: approval_request_id
          description: |-
            The ID of the approval request for this time allocation, if any.
             Each time allocation may have its own approval round (e.g., initial request
             vs. extension each go through separate approval).
          nullable: true
          readOnly: true
          x-stainless-terraform-configurability: computed
      title: AccessRequestTimeAllocation
      additionalProperties: false
      description: |-
        A time allocation represents a single grant (or pending grant) of access
         time within an access request. When an access request is first created, one
         time allocation is created alongside it with the initially requested
         duration. If the user later extends the request, the current time allocation
         is invalidated (reason = SUPERSEDED) and a brand-new time allocation is
         created with the updated duration. This means an access request accumulates
         a history of time allocations over its lifetime, but at most one is active
         and at most one is pending at any given moment.
    svflow.pubapimodels.AccessRequestTimeAllocationStatus:
      type: string
      title: AccessRequestTimeAllocationStatus
      enum:
        - ACCESS_REQUEST_TIME_ALLOCATION_STATUS_UNSPECIFIED
        - ACCESS_REQUEST_TIME_ALLOCATION_STATUS_PENDING
        - ACCESS_REQUEST_TIME_ALLOCATION_STATUS_ACTIVE
        - ACCESS_REQUEST_TIME_ALLOCATION_STATUS_INVALIDATED
      description: The status of an access request time allocation.
    svflow.pubapimodels.AccessRequestTimeAllocationInvalidationReason:
      type: string
      title: AccessRequestTimeAllocationInvalidationReason
      enum:
        - ACCESS_REQUEST_TIME_ALLOCATION_INVALIDATION_REASON_UNSPECIFIED
        - ACCESS_REQUEST_TIME_ALLOCATION_INVALIDATION_REASON_SUPERSEDED
        - ACCESS_REQUEST_TIME_ALLOCATION_INVALIDATION_REASON_CANCELED
        - ACCESS_REQUEST_TIME_ALLOCATION_INVALIDATION_REASON_REJECTED
        - ACCESS_REQUEST_TIME_ALLOCATION_INVALIDATION_REASON_CONCLUDED
      description: The reason a time allocation was invalidated.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````